gov.nist.nlpir.irf.proxy
Class VirtualProxy

java.lang.Object
  |
  +--gov.nist.nlpir.irf.proxy.VirtualProxy
Direct Known Subclasses:
ProxyDataElem, ProxyDocument, ProxyFeatureList, ProxyIndex, ProxyIndexingFeature

public abstract class VirtualProxy
extends java.lang.Object
implements java.io.Serializable

This is an abstract class which represents what's common to all proxies for support of on-demand (de)materialization of the real objects for which they stand.

Version:
$Revision: 1.13 $
Author:
This software was produced by NIST, an agency of the U.S. government, and by statute is not subject to copyright in the United States. Recipients of this software assume all responsibilities associated with its operation, modification and maintenance.
See Also:
Serialized Form

Inner Class Summary
private  class VirtualProxy.IMP_Entry
           
 
Field Summary
protected  PersistenceBroker broker
          The persistence broker for this proxy's real object
protected static HandlesByOid handles
          The table of handles by Oid.
private static java.util.Vector inMemoryProxiesByOid
          Tracks in-memory proxies for persistent objects to prevent duplication.
protected static InfoServer iS
          The info server - here to save getting it every time its needed.
protected  Oid objectIdentifier
          Unique identifier for persistent object
private  java.lang.Object realObject
          The real object for which this object is a proxy, a handle, a smart reference
(package private) static long serialVersionUID
          serial version universal id - put here so Java does not insert one which may change due to revisions and make it impossible to deserialize earlier versions of serialized objects
 
Constructor Summary
VirtualProxy()
           
 
Method Summary
 VirtualProxy addRefToInMemoryProxiesByOid()
          Adds to the table of in-memory proxies a reference to the specified proxy returning any existing one if one exists
abstract  PersistenceBroker createBroker()
          The concrete virtual proxy will create a broker for this proxy object
 void deleteRefFromInMemoryProxiesByOid()
          Deletes from the table of in-memory proxies a reference to the specified proxy
private  Handle dematerializeRealObject(Handle oldHandle, java.lang.Object obj)
          Dematerializes the updated real object for which this proxy object stands
private  Handle dematerializeRealObject(java.lang.Object obj)
          Dematerializes the real object for which this proxy object stands
protected  PersistenceBroker getBroker()
          Returns the broker for this proxy
 VirtualProxy getFirstInstance()
          Enforce uniqueness of proxies by checking to see if a proxy for this IR document already exists and returning that reference if it exists.
static int getInMemoryProxiesByOidBinCount()
          Gets the number of bins in the subject table
static int getInMemoryProxiesByOidSize()
          Gets the number of keys in the subject table
static java.lang.String getInMemoryProxyCounts()
          Returns information on the number of in-memory proxies for persistent objects - lightweight versus heavyweight
 Oid getObjectIdentifier()
          Gets this proxy's Oid
protected  PersistenceBroker getPersistenceBroker()
          Get the broker for this proxy object
static VirtualProxy getProxyFor(java.lang.Class proxyClass, Oid objectIdentifier)
          If there is already a proxy with the specified Oid, then return it after recording another reference to said proxy.
 java.lang.Object getRealObject()
          Returns the real object for which this proxy object stands
protected  boolean isLightweight()
          Tests whether this proxy is lightweight or not.
 void makeLightweight()
          Make this proxy object lightweight - cut the link to its real object
 void makePersistent()
          Makes the object persistent IFF not already persistent Assign it an oid if it has none; save its handle by Oid; and save the Oid in the proxie
private  java.lang.Object materializeRealObject()
          Materializes the real object for which this proxy object stands
static void presentInMemoryProxies()
          Writes the contents of the inMemoryProxiesByOid table to standard out
 void readExternal(BufferedRandomAccessFile in)
          Reads external representation of this object
 void replaceRealObject()
          Replaces the realobject associated with this proxy.
protected  void setBroker(PersistenceBroker b)
          Sets the broker field
static void setIS(InfoServer pIS)
          Sets the info server reference
(package private)  void setObjectIdentifier(Oid objectIdentifier)
           
protected  void setRealObject(java.lang.Object o)
          Sets the real object field
private static void testInMemoryProxiesByOidTable(long oid)
          Tests whether the InMemoryProxiesByOid table is large enough to accept this oid.
 java.lang.String toString()
          Returns the class instance as string.
 void writeExternal(BufferedRandomAccessFile out)
          Writes external representation of this object
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait
 

Field Detail

inMemoryProxiesByOid

private static transient java.util.Vector inMemoryProxiesByOid
Tracks in-memory proxies for persistent objects to prevent duplication. key = objectIdentifier; value = VirtualProxy

broker

protected transient PersistenceBroker broker
The persistence broker for this proxy's real object

realObject

private transient java.lang.Object realObject
The real object for which this object is a proxy, a handle, a smart reference

serialVersionUID

static final long serialVersionUID
serial version universal id - put here so Java does not insert one which may change due to revisions and make it impossible to deserialize earlier versions of serialized objects

objectIdentifier

protected Oid objectIdentifier
Unique identifier for persistent object

iS

protected static InfoServer iS
The info server - here to save getting it every time its needed. This assumes the IrfManager is created before this class is loaded.

handles

protected static HandlesByOid handles
The table of handles by Oid. Here for ease of access
Constructor Detail

VirtualProxy

public VirtualProxy()
Method Detail

getObjectIdentifier

public Oid getObjectIdentifier()
Gets this proxy's Oid
Returns:
this proxy's Oid

setIS

public static void setIS(InfoServer pIS)
Sets the info server reference

makePersistent

public void makePersistent()
Makes the object persistent IFF not already persistent Assign it an oid if it has none; save its handle by Oid; and save the Oid in the proxie

replaceRealObject

public void replaceRealObject()
Replaces the realobject associated with this proxy. Call it when the object has changed. Change only makes sense if there is a real object in memory, different from the one on disk. Therefore this method does nothing if there is no realObject reference. (Moral: makeLightweight() makes replaceRealObject() impossible. Replace before making lightweight.)

getRealObject

public final java.lang.Object getRealObject()
Returns the real object for which this proxy object stands
Returns:
The real object for which this proxy stands

makeLightweight

public void makeLightweight()
Make this proxy object lightweight - cut the link to its real object

setBroker

protected final void setBroker(PersistenceBroker b)
Sets the broker field
Parameters:
the - broker for this proxy

getBroker

protected final PersistenceBroker getBroker()
Returns the broker for this proxy
Returns:
the broker for this proxy

setRealObject

protected final void setRealObject(java.lang.Object o)
Sets the real object field
Parameters:
o - the real object for this proxy

isLightweight

protected final boolean isLightweight()
Tests whether this proxy is lightweight or not. For this method, a proxy is considered lightweight if its realObject reference is null.
Returns:
true if the realObject reference is null.

setObjectIdentifier

final void setObjectIdentifier(Oid objectIdentifier)

getPersistenceBroker

protected final PersistenceBroker getPersistenceBroker()
Get the broker for this proxy object
Returns:
the broker for this object

materializeRealObject

private final java.lang.Object materializeRealObject()
Materializes the real object for which this proxy object stands
Returns:
the real object for which this proxy stands

dematerializeRealObject

private final Handle dematerializeRealObject(java.lang.Object obj)
Dematerializes the real object for which this proxy object stands
Parameters:
obj - the object to be dematerialized/deserialized
Returns:
Handle of the designated object

dematerializeRealObject

private final Handle dematerializeRealObject(Handle oldHandle,
                                             java.lang.Object obj)
Dematerializes the updated real object for which this proxy object stands
Parameters:
oldHandle - The handle the object used to have.
Returns:
the new handle for the object. May be the same.

getFirstInstance

public VirtualProxy getFirstInstance()
Enforce uniqueness of proxies by checking to see if a proxy for this IR document already exists and returning that reference if it exists. Default definition. Override it if the Proxy refers to a class potentially containing proxies to call getFirstIntances() on this class.
Principle: when a proxy comes back from disk, it may be redundant with one already existing. There is no easy way to test it from inside the proxy, so the client is responsible for the unicity of the proxy by calling this function on it right after it is created.
Example:
 Proxy1 myProxy = readProxy1FromDisk();
 myProxy = myProxy.getFirstInstance();
 
Of course, if at one point it is sure this instance of the proxy is the first one to be materialized, then the call to this function can be avoided.
Note on Proxy-containers Objects: If a Proxy X refers to an object Y that may contain proxies, then Y must contain a void getFirstInstances() method, and an overriding of the current method in the proxy X must apply it to Y. If an object is a container of container of Proxies, it must define a void getFirstInstances() that recursively calls the same method on the contained container, and so on.
Note on non-Proxy Objects: On non-Proxy object, the method has no return value because it is just used to pass the recursive call.

getProxyFor

public static final VirtualProxy getProxyFor(java.lang.Class proxyClass,
                                             Oid objectIdentifier)
If there is already a proxy with the specified Oid, then return it after recording another reference to said proxy. Otherwise create a proxy (an instance of proxyClass), add it to the table and return it.
Parameters:
proxyClass - Class of the proxy to be gotten
objectIdentifier - Oid of the proxy to tobe gotten

createBroker

public abstract PersistenceBroker createBroker()
The concrete virtual proxy will create a broker for this proxy object
Returns:
the broker for this object

toString

public java.lang.String toString()
Returns the class instance as string.
Returns:
the class instance as string
Overrides:
toString in class java.lang.Object

readExternal

public final void readExternal(BufferedRandomAccessFile in)
Reads external representation of this object
Parameters:
in - random access file handle

writeExternal

public final void writeExternal(BufferedRandomAccessFile out)
Writes external representation of this object
Parameters:
out - random access file handle

addRefToInMemoryProxiesByOid

public final VirtualProxy addRefToInMemoryProxiesByOid()
Adds to the table of in-memory proxies a reference to the specified proxy returning any existing one if one exists
Parameters:
Oid - the object identifier of the proxy to be added

deleteRefFromInMemoryProxiesByOid

public final void deleteRefFromInMemoryProxiesByOid()
Deletes from the table of in-memory proxies a reference to the specified proxy
Returns:
virtual proxy

getInMemoryProxiesByOidSize

public static final int getInMemoryProxiesByOidSize()
Gets the number of keys in the subject table
Returns:
number of keys in inMemoryProxiesByOid table

getInMemoryProxiesByOidBinCount

public static final int getInMemoryProxiesByOidBinCount()
Gets the number of bins in the subject table
Returns:
number of bins in inMemoryProxiesByOid table

getInMemoryProxyCounts

public static java.lang.String getInMemoryProxyCounts()
Returns information on the number of in-memory proxies for persistent objects - lightweight versus heavyweight
Returns:
a string containing the information

presentInMemoryProxies

public static void presentInMemoryProxies()
Writes the contents of the inMemoryProxiesByOid table to standard out

testInMemoryProxiesByOidTable

private static void testInMemoryProxiesByOidTable(long oid)
Tests whether the InMemoryProxiesByOid table is large enough to accept this oid. If it's not, it extends the table. The current extension of the table is an increment of 50, but this makes the table allocated again and again. That's why a better solution would be to multiply its size by a factor of 1.2. There will be an int overflow problem if there are more than 2^31 (current int maximum) oids to store.