Holger's Java API

## com.antelmann.db
Class Stub<T extends DBEntry>

    java.lang.Object
      com.antelmann.db.AbstractDBEntry
          com.antelmann.db.Stub<T>

All Implemented Interfaces:
  DBEntry, DBReference, DetailedString, Serializable, Comparable<Stub<?>>

    public class Stub<T extends DBEntry>

extends AbstractDBEntry
implements Comparable<Stub<?>>, DBReference, DetailedString

a Stub is a small object that can serve as a proxy for larger objects, so that you can maintain a lot of these in memory and only access the full object if needed. All this object maintains is the ID, a String to properly display the instance via `toString()` and a reference to the original class. A Stub is useful to allow displaying a huge list of objects w/o actually having to instantiate the entire object at the time of selecting one from the list. Accessing the full instance can then be delayed until a single Stub is selected. As opposed to a standard DBReference, a Stub cannot be an 'empty' reference.

Since:
  16. November 2006, 14:05
Author:
  Holger Antelmann
See Also:
  `Database`, `DefaultDBReference`, Serialized Form

Field Summary

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

Fields inherited from interface com.antelmann.db.DBEntry
`ENTRY_FLAVOR, ENTRY_LIST_FLAVOR`

Constructor Summary
`Stub(Object id, Object displayValue, Class<T> originalClass)`

Method Summary

`static

`<T extends DBEntry> Stub<T>`

`

`asStub(T entry)`

`static

`<T extends DBEntry> Stub<T>`

`

`castStub(Stub<?> stub, Class<T> t)`

`int` `compareTo(Stub<?> stub)` uses the default UniversalComparator on the displayValue and then on the ID
`void` `ensureReferenceString(Database<?> db)`
`void` `ensureReferenceString(DBClassStore<T> store)`
`boolean` `equals(Object obj)`
`Object` `getDisplayValue()`
`static PatternExtractor<Stub<?>,Object>` `getIDExtractor()`
`Class<T>` `getOriginalClass()` returns the class that this stub represents, so that it is available at runtime and can be used to find the right DBClassStore from a Database.
`T` `getOriginalInstance(Database<?> db)` retrieves and returns the original object for this stub
`T` `getOriginalInstance(DBClassStore<T> store)` retrieves and returns the original object for this stub
`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

`<T extends DBEntry> PatternExtractor<T,Stub<T>>`

`

`getStubExtractor()`

`boolean` `isSameReference(DBReference ref)`
`static boolean` `isSameReference(DBReference ref1, DBReference ref2)`
`static Stub<?>` `makeStub(DBReference ref)` if the given reference is already a stub, the same is returned; null parameter or empty references result in null as a return value

`static

`<T extends DBEntry> Stub<T>`

`

`makeStub(DBReference ref, Class<T> type)`
combines `makeStub(DBReference)` and `castStub(Stub, Class)`

`static

`<T extends DBEntry> Stub<T>`

`

`makeStub(Object id, Object displayValue, Class<T> type)`

`boolean` `refersTo(DBEntry entry)`
`void` `reloadDisplayValue(Database<?> db)`
`void` `reloadDisplayValue(DBClassStore<T> store)`
`Stub<T>` `reloadInstance(Database<?> db)`
`Stub<T>` `reloadInstance(DBClassStore<T> store)`
`void` `setDisplayValue(Object displayValue)`
`String` `toDetailedString()` provides full details of this instance in a String.
`String` `toString()` returns the toString() value of the displayValue or an empty String if displayValue is null

`static

`<T extends DBEntry> Stub<T>`

`

`verify(Stub<?> stub, Class<T> type)`
verifies that the given stub is indeed of the given type

Methods inherited from class com.antelmann.db.AbstractDBEntry
`getID, hashCode, hashEntry, sameEntry`

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

Constructor Detail

### Stub

    public Stub(Object id,
                Object displayValue,
                Class<T> originalClass)

Method Detail

### asStub

    @Warning(value="this unchecked call may actually contain a stub of ? extends T")
    public static <T extends DBEntry> Stub<T> asStub(T entry)

### getStubExtractor

    public static <T extends DBEntry> PatternExtractor<T,Stub<T>> getStubExtractor()

### getIDExtractor

    public static PatternExtractor<Stub<?>,Object> getIDExtractor()

### makeStub

    public static <T extends DBEntry> Stub<T> makeStub(Object id,
                                                       Object displayValue,
                                                       Class<T> type)

### makeStub

    public static Stub<?> makeStub(DBReference ref)

  if the given reference is already a stub, the same is returned; null parameter or empty references result in null as a return value

### makeStub

    public static <T extends DBEntry> Stub<T> makeStub(DBReference ref,
                                                       Class<T> type)
                                            throws ClassCastException

  combines `makeStub(DBReference)` and `castStub(Stub, Class)`

  Throws:
    `ClassCastException`

### castStub

    public static <T extends DBEntry> Stub<T> castStub(Stub<?> stub,
                                                       Class<T> t)
                                            throws ClassCastException

  Throws:
    `ClassCastException`

### verify

    public static <T extends DBEntry> Stub<T> verify(Stub<?> stub,
                                                     Class<T> type)
                                          throws IllegalArgumentException

  verifies that the given stub is indeed of the given type

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

### getDisplayValue

    public Object getDisplayValue()

### setDisplayValue

    public void setDisplayValue(Object displayValue)

### compareTo

    public int compareTo(Stub<?> stub)

  uses the default UniversalComparator on the displayValue and then on the ID

  Specified by:
    `compareTo` in interface `Comparable<Stub<?>>`

### toString

    public String toString()

  returns the toString() value of the displayValue or an empty String if displayValue is null

  Overrides:
    `toString` in class `AbstractDBEntry`

### toDetailedString

    public String toDetailedString()

  Description copied from interface: `DetailedString`
  provides full details of this instance in a String. In case the String contains multiple lines, it is recommended to use '\n' rather than the platform specific line-break for better compatibility.

  Specified by:
    `toDetailedString` in interface `DetailedString`
  Returns:
    a (potentially multi-line) String providing full details on this object instance

### getOriginalClass

    public final Class<T> getOriginalClass()

  returns the class that this stub represents, so that it is available at runtime and can be used to find the right DBClassStore from a Database.

### ensureReferenceString

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

  Throws:
    `DatabaseException`

### ensureReferenceString

    public void ensureReferenceString(DBClassStore<T> store)
                               throws DatabaseException

  Throws:
    `DatabaseException`

### reloadInstance

    public Stub<T> reloadInstance(Database<?> db)
                                           throws DatabaseException

  Throws:
    `DatabaseException`

### reloadInstance

    public Stub<T> reloadInstance(DBClassStore<T> store)
                                           throws DatabaseException

  Throws:
    `DatabaseException`

### reloadDisplayValue

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

  Throws:
    `DatabaseException`

### reloadDisplayValue

    public void reloadDisplayValue(DBClassStore<T> store)
                            throws DatabaseException

  Throws:
    `DatabaseException`

### getOriginalInstance

    public T getOriginalInstance(Database<?> db)
                                          throws DatabaseException

  retrieves and returns the original object for this stub

  Throws:
    `DatabaseException`

### getOriginalInstance

    public T getOriginalInstance(DBClassStore<T> store)
                                          throws DatabaseException

  retrieves and returns the original object for this stub

  Throws:
    `DatabaseException`

### equals

    public boolean equals(Object obj)

  Overrides:
    `equals` in class `AbstractDBEntry`

### refersTo

    public final boolean refersTo(DBEntry entry)

### isSameReference

    public final boolean isSameReference(DBReference ref)

### isSameReference

    public static boolean isSameReference(DBReference ref1,
                                          DBReference ref2)

  See Also:
    `DefaultDBReference.sameReference(DBReference, DBReference)`

### getReferenceID

    public final 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()`, `DefaultDBReference.isConsistent(DBReference)`

### getReferenceClass

    public final 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()`, `DefaultDBReference.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`

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