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