Holger's Java API

## com.antelmann.db
Class DefaultDBReference

    java.lang.Object
      com.antelmann.db.DefaultDBReference

All Implemented Interfaces:
  DBReference, Serializable

    public class DefaultDBReference

extends Object
implements DBReference

this class implements a simple DBReference object. This implementation is immutable in regards to the database reference itself; merely the reference string can be altered after construction. A DefaultDBReference may be 'empty'.

Since:
  22. August 2007, 22:16
Author:
  Holger Antelmann
See Also:
  `Stub`, Serialized Form

Field Summary
`static DefaultDBReference` `EMPTY_REF` provides an empty DBReference (i.e. its id, class and string are null)

Fields inherited from interface com.antelmann.db.DBReference
`REFERENCE_FLAVOR, REFERENCE_LIST_FLAVOR`

Constructor Summary
`DefaultDBReference(Database<?> db, Object referenceID, Class<? extends DBEntry> referenceClass)`
`DefaultDBReference(DBClassStore<?> store, Object referenceID)`
`DefaultDBReference(DBReference ref)`
`DefaultDBReference(Object referenceID, Class<?> referenceClass, String referenceString)`
`DefaultDBReference(String str)` an empty reference that merely contains the string as info

Method Summary
`DBEntry` `dereference(Database<?> db)`
`void` `ensureReferenceString(Database<?> db)`
`static void` `ensureReferenceString(DBReference ref, Database<?> db)`
`boolean` `equals(Object obj)` returns true if the given object is a DBReference and is also the same reference as defined in `sameReference(DBReference)`
`static DefaultDBReference` `fromEntry(DBEntry entry)`
`Class<? extends DBEntry>` `getReferenceClass()` indicates the type of DBEntry that represents the class of the reference ID, so that the instance could be looked up in a Database; this may be null only if the reference itself is null, too.
`Object` `getReferenceID()` returns the ID of the DBEntry this instance refers to; this may be null only if the reference type returns null, too.
`String` `getReferenceString()` provides a meaningful (displayable) description for the referenceID/referenceType or null if there is no reference for this entry.
`static Comparator<DBReference>` `getRefStringComparator()`
`int` `hashCode()`
`static boolean` `isAllNull(DBReference ref)`
`static boolean` `isConsistent(DBReference ref)` returns true only if the given reference applies to the rule that all relevant values (reference class and reference id) are both either null or non-null.
`boolean` `isEmpty()`
`static boolean` `isEmpty(DBReference ref)` if true is returned, this reference may still contain a reference string
`boolean` `isInstanceOf(Class<?> type)`
`static boolean` `isInstanceof(DBReference ref, Class<?> type)`
`boolean` `refersTo(DBEntry entry)`
`static boolean` `refersTo(DBReference ref, DBEntry entry)`
`boolean` `sameReference(DBReference ref)`
`static boolean` `sameReference(DBReference ref1, DBReference ref2)` determines whether both given references refer to the same entry
`void` `setReferenceString(String referenceString)`
`String` `toString()`
`static DBReference` `verify(DBReference ref, Class<?> type)` verifies that the given reference is indeed of the given type
`static DBReference` `verifyBase(DBReference ref, Class<?> baseType)`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### EMPTY_REF

    public static final DefaultDBReference EMPTY_REF

  provides an empty DBReference (i.e. its id, class and string are null)

Constructor Detail

### DefaultDBReference

    public DefaultDBReference(DBClassStore<?> store,
                              Object referenceID)
                       throws DatabaseException

Throws:
  `DatabaseException`

### DefaultDBReference

    public DefaultDBReference(Database<?> db,
                              Object referenceID,
                              Class<? extends DBEntry> referenceClass)

### DefaultDBReference

    public DefaultDBReference(Object referenceID,
                              Class<?> referenceClass,
                              String referenceString)
                       throws IllegalArgumentException

Parameters:
  `referenceID` - the ID of the referenced entry (or null if this is an empty reference and the referenceClass is also null)
  `referenceClass` - must be a class implementing DBEntry (in not null)
  `referenceString` - an optional String representing the entry this reference is referring to
Throws:
  `IllegalArgumentException` - if `DBEntry` class is not assignable from the non-null referenceClass

### DefaultDBReference

    public DefaultDBReference(DBReference ref)

### DefaultDBReference

    public DefaultDBReference(String str)

  an empty reference that merely contains the string as info

Method Detail

### fromEntry

    public static DefaultDBReference fromEntry(DBEntry entry)

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

### getReferenceID

    public Object getReferenceID()

  Description copied from interface: `DBReference`
  returns the ID of the DBEntry this instance refers to; this may be null only if the reference type returns null, too.

  Specified by:
    `getReferenceID` in interface `DBReference`
  See Also:
    `DBEntry.getID()`, `isConsistent(DBReference)`

### getReferenceClass

    public Class<? extends DBEntry> getReferenceClass()

  Description copied from interface: `DBReference`
  indicates the type of DBEntry that represents the class of the reference ID, so that the instance could be looked up in a Database; this may be null only if the reference itself is null, too.

  Specified by:
    `getReferenceClass` in interface `DBReference`
  See Also:
    `Database`, `DBEntry#getClass()`, `isConsistent(DBReference)`

### getReferenceString

    public String getReferenceString()

  Description copied from interface: `DBReference`
  provides a meaningful (displayable) description for the referenceID/referenceType or null if there is no reference for this entry. Normally, this method would provide some cached info about the reference w/o having to dereference the link through the database. Note that this method may return null even if the reference itself is not null.

  Specified by:
    `getReferenceString` in interface `DBReference`

### setReferenceString

    public void setReferenceString(String referenceString)

### ensureReferenceString

    public void ensureReferenceString(Database<?> db)
                               throws DatabaseException

  Throws:
    `DatabaseException`

### ensureReferenceString

    public static void ensureReferenceString(DBReference ref,
                                             Database<?> db)
                                      throws DatabaseException,
                                             UnsupportedOperationException

  Throws:
    `DatabaseException`
    `UnsupportedOperationException`

### dereference

    public DBEntry dereference(Database<?> db)
                        throws DatabaseException

  Throws:
    `DatabaseException`

### isInstanceOf

    public boolean isInstanceOf(Class<?> type)

### isInstanceof

    public static boolean isInstanceof(DBReference ref,
                                       Class<?> type)

### refersTo

    public boolean refersTo(DBEntry entry)

### refersTo

    public static boolean refersTo(DBReference ref,
                                   DBEntry entry)

### sameReference

    public boolean sameReference(DBReference ref)

### sameReference

    public static boolean sameReference(DBReference ref1,
                                        DBReference ref2)

  determines whether both given references refer to the same entry

### isEmpty

    public boolean isEmpty()

### isEmpty

    public static boolean isEmpty(DBReference ref)
                           throws InconsistentContentException

  if true is returned, this reference may still contain a reference string

  Throws:
    `InconsistentContentException` - if only one (id or class) is null

### isAllNull

    public static boolean isAllNull(DBReference ref)

### isConsistent

    public static boolean isConsistent(DBReference ref)

  returns true only if the given reference applies to the rule that all relevant values (reference class and reference id) are both either null or non-null.

### verify

    public static DBReference verify(DBReference ref,
                                     Class<?> type)
                              throws IllegalArgumentException

  verifies that the given reference is indeed of the given type

  Parameters:
    `ref` - the reference to be checked
    `type` - the expected type for the reference
  Returns:
    the given reference if it was successfully verified
  Throws:
    `IllegalArgumentException` - if the given reference was not of the given type
  See Also:
    `Stub.verify(Stub, Class)`

### verifyBase

    public static DBReference verifyBase(DBReference ref,
                                         Class<?> baseType)
                                  throws IllegalArgumentException

  Throws:
    `IllegalArgumentException`

### equals

    public boolean equals(Object obj)

  returns true if the given object is a DBReference and is also the same reference as defined in `sameReference(DBReference)`

  Overrides:
    `equals` in class `Object`

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `Object`

### getRefStringComparator

    public static Comparator<DBReference> getRefStringComparator()

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads