Dark Planet Development Platform

Persistence API

1. Data model storage methods, which cover storing and retrieving instances of the data model; and,
2. Hibernate factory and session methods, which cover obtaining Hibernate sessions for accessing various types of data, as well as factory methods to simplify constructing records for storage via Hibernate.

API Overview

The "save" and "load" methods provide the basic mechanism for storing and later retrieving data model information. Data model objects are designed to be persisted via Java serialization. However, persistence API implementations are free to store data model instances however they like. The "get" methods allow for discovering all available persisted data model information.

The second group of methods in the persistence API provide methods for working with Hibernate stored data, of which we only show a subset here:

Working with Hibernate stored data requires a Session which is normally provided by a SessionFactory. In DPS there are two distinct groups of Hibernate tables:

• Generic tables, which store information not related to a particular character or corporation. An example is market data.
• Keyed tables, which store character or corporation public or private data. An example is wallet journal records.

The two "get...SessionFactory" methods provide a means to get an appropriate factory for working with each type of data. We distinguish the two types of data to allow more flexibility in storage.

A "record" represents a data object stored (or intended to be stored) in a Hibernate table. Most of the methods in the persistence API are factory methods which allow the construction of new records. The arguments to a factory method are always the key columns of the table in which the record will be stored. For example, the full specification of the "getNewJournalRecord" methods is:

     IWalletJournalRecord getNewJournalRecord(int keyID, long charOrCorpID, int accountKey, long refID);

• The keyID of the character or corporation which owns the record.
• The character or corporation ID of the owning character or corporation.
• The account key of the wallet division where the journal entry is stored.
• The EVE server reference ID of the journal entry.

Record key columns are chosen to allow as much flexibility as possible in the persistence API implementation. For example, since "keyID" is a key column, you can choose to store all records in a single common table shared across all characters or corporations. Or, for performance reasons, you may wish to store character and corporation data in completely separate tables.

Example: Using the Store and Retrieve Methods

     // Create a Capsuleer
     int keyID = ... you keyID ...;
     IEveDataModel dataModel = ... reference to your data model ...;
     IModelFactory factory = dataModel.getModelFactory();
     Capsuleer myCharacter = factory.makeCharacter(keyID, vCode, characterID);

     // Save our capsuleer
     IEvePersistenceFactory pFactory = ... reference to your persistence factory ...;
     pFactory.saveCharacter(myCharacter);

     // Verify that we can find it again
     Collection charKeys = pFactory.getCharacterKeys();
     assert charKeys.contains(keyID);
    
     // Reload
     Capsuleer loadedChar = pFactory.loadCharacter(keyID);

Example: Storing and Retrieving Records in Hibernate Tables

There are five steps to inserting data into a Hibernate table:

1. Create an instance of the class you wish to insert. Be sure to populate at least the key column fields.
2. Obtain a Session from a Hibernate SessionFactory.
3. Begin a transaction using your Session.
4. Use the "merge" or "update" method to save your class instance.
5. Commit the transaction or rollback.

	@Override
	public IWalletJournalRecord getNewJournalRecord(int keyID, long entityID,
			int accountKey, long refID) {
		WalletJournalRecordImpl newEntry = new WalletJournalRecordImpl();
		newEntry.setKeyID(keyID);
		newEntry.setEntityID(entityID);
		newEntry.setAccountKey(accountKey);
		newEntry.setRefID(refID);

		return newEntry;
	}

The class WalletJournalRecordImpl implements IWalletJournalRecord. The code here just ensures that the fields representing the key columns are always populated. It's up to the caller to populate everything else.

Beyond object construction, you can use the Hibernate API methods directly if needed to insert new records. Here's the code for the five step process we described above assuming we want to insert a new wallet journal record (using the persistence API to obtain a Session):

    // Create record to insert
    IEvePersistenceFactory persistFactory = ...get persist reference...;
    IWalletJournalRecord newRecord = persistFactory.getNewJournalRecord(keyID, entityID, accountKey, refID);
    ... populate other journal record fields ...;

    // Obtain session
    Session txn = persistFactory.getKeySessionFactory(keyID).openSession();

    try {
    
         // Start transaction
         txn.begin();

         // Store record
         txn.merge(newRecord);

         // Commit
         txn.commit();

    } catch (HibernateException e) {
         // Commit failed, rollback
         txn.rollback();
    }

In terms of storing your new record, there are at least choices:

1. You can save the record, which can be used for a unique new record, but will fail if the record already exists.
2. You can update the record. You would use this method if the object you are storing was already retrieved from the database and you are simply updating some fields.
3. You can merge the record, which acts like a save if the record is new, and acts like an update if the record already exists.

Records are retrieved from a Hibernate table in five steps:

1. Obtain a Session from a Hibernate SessionFactory.
2. Begin a transction using your Session.
3. Construct a query to obtain the object you want from the desired table.
4. Execute your query and save the result(s).
5. Commit the transaction or rollback.

    // Obtain session
    IEvePersistenceFactory persistFactory = ...get persist reference...;
    Session txn = persistFactory.getKeySessionFactory(keyID).openSession();

    // Assume we know the refID of the record we want
    long refID = ... refID we want ...;

    // This variable will store the results
    List results;

    try {
    
         // Start transaction
         txn.begin();

         // Construct a query
         Query select = txn.createQuery("from org.dps.core.persist.IWalletJournalRecord where refID = :refID");
         select.setLong("refID", refID);

         // Execute the query
         results = select.list();

         // Commit
         txn.commit();

    } catch (HibernateException e) {
         // Commit failed, rollback
         txn.rollback();
    }

While the DPS API provides many helper functions for inserting records, there are very few factory-type methods for performing queries. This is because the type of query needed will vary widely among different applications. Instead, DPS provides a few simple methods to make it easier to manage Session objects (see the discussion of the HibernateCachedData type here). It is largely up to user to construct their own queries.

For more details on query construction, see the Hibernate documentation here.