This package provides all the classes and interfaces required to use our 100% Java ODBMS solution, PJODeCS. PJODeCS is a small footprint ODBMS system with built-in support for single-user or thin-client/fast-server access to PJODe object databases. PJODeCSs client/server extensions provide an extremely easy to use, thread-safe API for creating and manipulating our PJODe database system from multiple machines asynchronously.

Below are details and examples on using PJODeCS in both single-user and client/server modes.

Single-user Setups

Single user setups assume that PJODeCS will be used to store information for an application where all data will be stored on the local filesystem and will be accessed only by applications on that machine. It is thread-safe and supports access to a single database by more than one application asynchronously.

Connecting to a database file
Connections to a PJODe database are obtained by creating an instance of PJODe through any of it's public constructors. Once an instance is created, the database is ready for data manipulation:
/**
 * Connect to database 'test.db'
 */
 PJODe db = new PJODe("test.db");
 System.out.println("Ready for data manipulation");

Adding objects to the database
Adding objects to a PJODe database is done through calls to {@link com.linxpda.PJODe.PJODe#set(Object) set(Object)}. This method performs add and update features automatically. Objects in PJODe are referenced through an integer ID number that is unique to each object added. Therefore if the same instance of an object is added to the database, it overwrites the current instance. There is no need for an update method:
/**
 * Add an object to our database..
 */
Person person1 = new Person("Tom Cole", "tcole@eclipsetel.com");
db.add(person1);
System.out.println("Added person1");

Removing objects from the database
Removing objects from PJODe is done through calls to {@link com.linxpda.PJODe.PJODe#remove(Object) remove(Object)}. As with the add method, the same instance of Object, as determined by it's ID number, will be removed from the database:
/**
 * Remove persone1 from our database...
 */
db.remove(person1);
System.out.println("person1 removed.");

Retrieving objects from the database
Retrieving objects from PJODe is done through a user defined query-by-example method. This definition occurs in the class's equals(Object) method. User defined classes may override this method to provide custom comparisons to other instances of the same object for determination of equality. In our person example (which will have only two fields, name and email) we will assume that any occurence of a string within a query field will be considered equals (as defined by String.indexOf(String)) and any fields that are null should be ignored and considered not essential in determing equality:
/**
 * Person class that defines custom query capabilities..
 */
import java.io.Serializable;

public class Person implements Serializable {
	protected String name;
	protected String email;
	
	public Person(String name, String email) {
		this.name = name;
		this.email = email;
	}
	
	public String toString() {
		return name + ", " + email;
	}
	
	public boolean equals(Object query) {
		if (query instanceof Person) {
			Person p = (Person) query;
			if (! p.name == null) {
				if (name.indexOf(p.name) < ))
					return false;
			}
			if (! p.email == null) {
				if (email.indexOf(p.email) < 0)
					return false;
			}
			return true;
		}
		else {
			return false;
		}
	}
}

Once we have a custom class defined, we create a query instance of Person to find anyone who has "Tom" in their name field:

Person query = new Person("Tom", null);
Now we call {@link com.linxpda.PJODe.PJODe#get(Object) get(Object)} passing it the query object. The results of a search are returned in an instance of {@link com.linxpda.PJODe.ResultSet ResultSet} which provides a simple API for navigating through a collection of Objects:
/**
 * Get all people with "Tom" in their names.
 * Email is irrelevant.
 */
ResultSet results = db.get(query);
System.out.println("Found " + results.getObjectCount() + " instances.");
for (int i = 0; i < results.getObjectCount(); i++) {
	System.out.println("  " + results.getObjectAt(i).toString());
}

Passing a null to get will return all objects in the database.

Closing a database
Now we're ready to close the database. Note that all transactions are performed in real-time so we do not need to close a db to commit data updates. This method simply closes any remote or local connections to the databae file.
/**
 * Close the database...
 */
db.close();
db = null;

That's it!

Client/Server setups

This setup assumes that multiple users on multiple machines will be accessing PJODe stored data asynchronously, from a variety of software applications. Client/Server useage of PJODeCS is nearly identical to the single-user setup with only two exceptions: 1) The {@link com.linxpda.PJODe.server.PJODeRMIServer PJODeRMIServer} needs to be started on the server machine and a remote instance of {@link com.linxpda.PJODe.PJODe PJODe} needs to be referenced.

Starting the PJODeRMIServer

You can start the PJODeRMIServer by either:

  • Double clicking the PJODeCS-obf.jar file which will bind the RMI server as "PJODe" on port 1099.

  • Run the PJODeRMIServer class providing remote name and port number you specify:

    java com.linxpda.PJODe.server.PJODeRMIServer <remote_name> <port>

    The above would bind a PJODeRMIServer with the name "remote_name" listening on port "port".

NOTE: You need only start one PJODeRMIServer to access any and all PJODe databases on the remote system.

Obtain Remote Instance of PJODe

Obtaining a remote reference to PJODe is just as easy as creating a single-user local instance, maybe even easier. Instead of calling one of the PJODe constructors, simply call the static {@link com.linxpda.PJODe.PJODe#getRemoteInstance(String, String) PJODe.getRemoteInstance(db_file, url)} method, which will search the 'url' for an instance of PJODeRMIServer and open a connection to the database 'db_file'. From there, all method calls against the remote instance are identical to a local single-user instance.

If you have any questions or difficulties in using PJODe, please contact us at support@linxpda.com