Persistency Tutorial

Persistency should basically provide you with means to persist collections of Contact and ContactGroup instances.

Persistency is modeled by the generic net.wimpi.pim.contact.db package. This package contains six interfaces defining the contract for implementations:

1. net.wimpi.pim.contact.db.ContactDatabase: For the contact database
2. net.wimpi.pim.contact.db.ContactCollection: For a collection of Contact instances
3. net.wimpi.pim.contact.db.ContactGroup: For groups of contacts
4. net.wimpi.pim.contact.db.ContactGroupCollection: For a collection of ContactGroup instances
5. net.wimpi.pim.contact.db.ContactFilter: For a filter that is capable of filtering Contact instances
6. net.wimpi.pim.contact.db.ContactGroupFilter: For a filter that is capable of filtering ContactGroup instances

Available implementations reside in subpackages of the same package; for the moment there is only a Serialization based implementation (see net.wimpi.pim.contact.db.serializable).

The basic way you can utilize a ContactDatabase should be fairly the same for any implementation:

The first step is to obtain the factory. At the moment you will only be able to obtain the default factory (the SerializableContactDBFactory); however, it is likely that in the future you can state a flavor when obtaining the factory instance:

ContactDBFactory cdbf = Pim.getContactDBFactory();

Then you can create ContactDatabase instance using the respective factory method:

ContactDatabase ctdb = cdbf.createContactDatabase();

Now you can add Contact and ContactGroup instances to the ContactDatabase, list them (with and without filters etc.). Please see the API Documentation for more information on the operations.

Group instances can also be obtained from the ContactDBFactory:

ContactGroup group = ctdb.createContactGroup();

jpim contains a ContactDatabase implementation, that is serializable. It can be stored and retrieved (from and to streams) using the standard Java serialization mechanism.

You can serialize the database to any type of OutputStream instance:

FileOutputStream fout = new FileOutputStream(ctdb.getUID() + ".ser");
ObjectOutputStream out = new ObjectOutputStream(fout);
out.writeObject(ctdb);

You can de-serialize the database from any type of InputStream instance:

FileInputStream fin = new FileInputStream(filename);
ObjectInputStream in = new ObjectInputStream(fin);
ContactDatabase ctdb = (ContactDatabase) in.readObject();