Package org.apache.jdo.impl.fostore

This package contains the implementation of the File/Object Store JDO Reference Implementation (FOStore, pronounced "foster").

See:
          Description

Interface Summary
FieldRequest Represents a request to manipulate (read or update) the fields of an object.
FOStoreClientConnection Represents the connection as seen by the client.
FOStoreConnection Tagging interface at root of all kinds of FOStore connections.
FOStoreConnectionFactory.CFAccessor CFAccessor implementation instances allow copying values to/from a FOStoreConnectionFactory and a Properties.
FOStoreServerConnection A connection as used by a server/store.
Request Represents the ability to send information to the actual file/object store.
RequestFactory Creates different kinds of requests.
RequestFinisher Means by which a request can indicate that there is work to be done once all requests have been processed.
RequestHandler.HandlerFactory Means by which subclasses are created.
 

Class Summary
AbstractFieldManager An implementation of FieldManager in which all methods throw a FOStoreAbstractMethodException with the name of the method invoked.
AbstractFieldRequest This is an AbstractRequest that uses an exception-throwing implementation FieldManager to implement that interface.
AbstractRequest Base implementation for all Request subtypes.
ActivateClassHandler Process requests to activate classes.
ActivateClassRequest Represents a request to cause the description of a class in the client to have a representation in the store.
AID Represents the identity of a JDO object in the File/Object store.
AIDTranscriber  
BeginTxHandler Process BeginTx requests.
BeginTxRequest Represents a request to inform the store that a transaction is beginning.
Block Represents an object stored in the database as a semi-opaque value.
BooleanTranscriber Transcribes boolean values.
BufferedRequestFactory Creates different kinds of requests.
ByteTranscriber Transcribes byte values.
CharTranscriber Transcribes char values.
CLID Represents a class id.
CommitHandler Process Commit requests.
CommitRequest Represents a request to cause previous insert, update, and so on operations since the previous Commit or Rollback request to commit to the datastore.
CreateOIDHandler Process CreateOIDRequests.
CreateOIDRequest Causes a datastore OID to be associated with a provisional OID.
DBClass Represents a class stored in the database.
DBExtent Represents a set of instances of a given class stored in the database.
DBInfo This class represents the information about the contents of the store itself which must be durable across JVMs.
DeleteHandler Processes requests to delete objects from the datastore.
DeleteRequest Represents a requests to remove a persistent object in the store.
DoubleTranscriber Transcribes double values.
DummyTranscriber This Transcriber is used to skip managed non-persistent fields.
Dumper Provides information such as metadata, extents, objects about the store.
Dumper.ClassInstancesRequest DumpRequest that dumps information about the instances of a class.
Dumper.ClassMetadataRequest DumpRequest that dumps metadata about a class.
Dumper.ClassRequest Abstract DumpRequest that assists in dumping information about classes.
Dumper.ClassSubclassesRequest DumpRequest that dumps information about the subclasses of a class.
Dumper.DBInfoRequest DumpRequest that can dump DBInfo.
Dumper.DumpOptionSubRequest Abstract class for dumping database information.
DumpHandler Process dump requests.
DumpOption Diagnostic code to identify a dump request to the store.
DumpRequest Represents a request to dump information from the store.
FetchHandler Process fetch requests.
FetchRequest Represents a request to read the values of one or more fields for a persistent object from the store.
FieldFetcher Extend AbstractFieldManager overriding only fetchABCField methods
FloatTranscriber Transcribes float values.
FOStoreBtreeStorage FOStore specific BtreeStorage subclass.
FOStoreBtreeStorage.Resolver Dummy implementation.
FOStoreClientConnectionImpl Implementation of the client side of a FOStore connection.
FOStoreConnectionFactory A connection factory for FOStore.
FOStoreConnectionId Represents the information required to connect to a database.
FOStoreConnector FOStoreConnector represents a connection to the FOStoreDatabase.
FOStoreDatabase File/Object Store Database, using an underlying Btree implementation.
FOStoreExtent This is an in-memory extent.
FOStoreInput Extend ByteArrayInputStream so that we can get ahold of the byte array and current position, and can change the current position.
FOStoreLocalConnection Implements the client and server/store connections for the case in which the client and store are running in the same address space.
FOStoreModel Provides model information required by fostore: mapping between CLID's and the java.lang.Class's.
FOStoreOutput Extend ByteArrayOutputStream so that we can get ahold of the byte array and current position, and can make sure we have enough space to write an object.
FOStorePM Subclass of #PersistenceManagerImpl implementing abstract methods newQuery.
FOStorePMF The File/Object Store's implementation of a PersistenceManagerFactory.
FOStorePMFFactory Creates a FOStorePMF when read in via JNDI.
FOStoreRemoteConnection Represents a connection to a store that runs in a JVM separate from that of a client.
FOStoreSchemaUID A FOStoreSchemaUID is an internal name used to distinguish persistence capable classes based on the structure of their persistent fields as indicated by the enhancer.
FOStoreServerConnectionImpl This class implements the FOStoreServerConnection contract.
FOStoreStoreManager StoreManager represents the datastore to the rest of the JDO components.
FOStoreTranscriber FOStoreTranscriber contains methods to transcribe each primitive type, but they all throw AbstractMethodError.
FOStoreTranscriberFactory Provides Transcriber instances for FOStore.
FOStoreURLStreamHandler Creates connections to databases.
GetClassHandler Process GetClass requests.
GetClassRequest Represents a request to get the java.lang.Class corresponding to a CLID.
GetExtentHandler Process GetExtent requests.
GetExtentRequest Represents a request to get the extent of a class and possibly its subclasses.
GetInstancesHandler Process GetInstances requests.
GetInstancesRequest Represents a request to fetch a batch of instances.
I18N Provides I18N information for FOStore.
InsertHandler Process requests to insert objects in the datastore.
InsertRequest Represents a request to write a new object to the datastore.
IntTranscriber Transcribes int values.
LoginHandler Handler for LoginRequests.
LoginRequest Request to login to a database.
LongTranscriber Transcribes long values.
Main Standalone server for FOStore databases.
Message Represents a set of one or more requests that will be sent to the store.
ObjectTranscriber Transcribes all non-primitive, non-String values.
OID Represents the identity of a JDO object in the File/Object store.
Reply Represents the result of processing a request.
ReplyHandler Processes replies that are received from the store.
RequestHandler This dispatches each request received by the store to the appropriate request-type-specific request handler.
RequestId Represents a simple id associated with a request.
RequestType Represents a kind of Request.
RollbackHandler Process Rollback requests.
RollbackRequest Represents a request to cause operations since the previous Commit or Rollback request to rollback.
ShortTranscriber Transcribes short values.
Status Represents a quick summary of the result of processing a request.
SubclassSet Represents a set of CLIDs of subclasses of a given class.
Tester Provides a relatively convient way to print debug messages.
Tester.Timer  
UpdateHandler Process requests to update instances in the datastore.
UpdateRequest Represents a request to change one or more fields of a persistent object in the store.
VerifyHandler Process requests to verify instances in the datastore.
VerifyRequest Represents a request to verify that in-memory data is the same as that in the database.
 

Exception Summary
FOStoreAbstractMethodException This exception means that a subclass didn't override a method that it should have.
FOStoreDatabaseException This provides an insulation layer between BtreeDatabase and FOStore.
FOStoreFatalInternalException This is an exception which _should_ never be thrown, as it indicates an error in the implementation, such as a bug that has been found.
FOStoreFatalIOException This is an exception which _should_ never be thrown, as it indicates an error in I/O traffic between client and server.
FOStoreLoginException This is an exception which _should_ never be thrown, as it indicates an error in the implementation, such as a bug that has been found.
FOStoreUnsupportedException This exception means that a FOStore doesn't have support for what is being requested.
 

Package org.apache.jdo.impl.fostore Description

This package contains the implementation of the File/Object Store JDO Reference Implementation (FOStore, pronounced "foster").

This file provides information for implementors and maintainers of the package.

Identity in FOStore and provisional ID's

All objects created by the client have a datastore-provided ID, called an Object Id (OID.java). Part of the OID represents the class of the object; these id's are called Class Id's and are separately managed (CLID.java). When an object is made persistent:

Employee emp = new Employee("John Doe", 12345);
PersistenceManager pm = PersistenceManagerFactory.getPersistenceManager();
pm.makePersistent(emp);

the object is assigned a "provisional" OID, assigned by the client, not by the datastore. When a real OID is required (getObjectId) or the transaction commits, the user's object is then flushed to the store, and a real ID is provided. The datastore provides a datastore ID corresponding to the provisional ID.

The mapping from provisional to real id's is maintained by both the client and the store. The client maintains it on a per-PMF basis (in FOStorePMF.java). The store maintains it for all clients (currently a single map, which is incorrect as it should be per-client; see FOStoreDatabase.java).

Similar tables are kept, separately, for CLIDs. These tables are in FOStoreModel.java on the client side, and in FOStoreDatabase.java on the store side. Recall that the OID of an object contains the CLID of the class of the object. If no instances of that class have yet been stored, then the OID contains a provisional CLID. The process of storing the object also stores a representation of the object's class, and creates a datastore-provided CLID.

The need for each of the tables is as follows:

OID, client: Assume a persistent object is created, and put into a persistent graph structure. Assume further that the object is comitted, but not the graph structure. At that point, the graph still refers to the object by its provisional OID. Having this table allows us to find the real object ID.

OID, store: Assume a graph structure of new objects is to be stored, in which a single object is referenced more than once. Each time it is referenced, it is with the provisional ID assigned by the client. The store must ensure that an object is only assigned a single datastore ID, and this table ensures that.

CLID, client: StoreManager implementations are required to be able to provide a java.lang.Class given an OID. When assigning OIDs, FOStore will never use a provisional CLID if the datastore-provided CLID is available. However, it is possible that two objects of the same class are created, and one is stored. The CLID table in FOStoreMetaData will, after the store, only the datastore-provided ID. If one then asks the store manager for the class of the unstored object by it's OID, we still have to provide the right answer. By keeping a mapping of provisional IDs to datastore IDs in this table, we can do so.

CLID, store: Exactly the same reasoning as for the OID table in the store: ensuring that a given class is only ever assigned a single CLID.

Storing and Fetching Objects

Objects are stored in the database by way of InsertRequest, and fetched by way of FetchRequest. Each contains several methods to store and fetch Java types. If in the unlikely event that more primitive types are added to Java, they will have to be added here. Also, support will have to be added to FieldManager, which is outside of FOStore in the common package, and to it's implementation in the fostore package, in AbstractFieldManager

More likely, however, is the need to extend the set of non-primitive types, such as Collection types, that FOStore supports. Support for these lies in 2 files: CLID.java and the various XXXTranscriber.java files. The first keeps a table of "known" CLID's, which maps between a java.lang.Class and a compiletime-fixed CLID. The latter has a Transcriber class for each of the known CLID's, for instance LocaleTranscriber writes and reads java.util.Locale objects to/from I/O streams.