Connection API¶

Using the Connection interface is a simple matter of obtaining a Connection object and executing commands with it.

Obtaining a Connection¶

Connections are obtained using the ConnectionFactory class. Call the newConnection() method using either a Session or a URI for the server.

Session Connections¶

These connections are created when you have access to a Session. This is the case with legacy code, and also when there is ready access to a SessionFactory object, such as a Database.

For instance, applications which embed a Mulgara instance will have an instance of Database. In this case a Connection can be created with the following:

  // The database is created with appropriate configuration
  Database database = ...;

  // create the connection factory
  [[ConnectionFactory]] connectionFactory = new [[ConnectionFactory]]();

  // get a session from the database
  Session session = database.newSession();

  // now create the connection
  Connection connection = connectionFactory.newConnection(session);

The Connection will now own the Session, and will close it when the Connection is closed. So there is no need to keep hold of a Session that is given to a Connection:

  Connection connection = connectionFactory.newConnection(database.getSession());
    // do something
  connection.close();

URL Connnections¶

Mulgara databases can also be accessed via URL. For a standalone database on a host called hostname the default URL will be:

rmi://hostname/server1

The hostname must always be a network resolvable host name (for instance, through DNS or a hosts file). The server name defaults to the name server1 but this is configurable either through a config file, system properties] or the [wikiArgs command line when starting the server.

For embedded databases (such as in the examples shown above in Session Connections) the URL will start with the "local" scheme instead of RMI. If a URL with the RMI scheme is used to access a local database, then the system should discover this and provide a local connection, and not an RMI connection.

The following is an example of creating a Connection by URL:

  // create the connection factory
  [[ConnectionFactory]] connectionFactory = new [[ConnectionFactory]]();

  // create a couple of URLs to this server and another
  URL thisMachine = new URL("rmi://localhost/server1");
  URL anotherMachine = new URL("rmi://192.168.0.12/server1");

  // now create the connections
  Connection thisConnection = connectionFactory.newConnection(thisMachine);
  Connection anotherConnection = connectionFactory.newConnection(anotherMachine);

Connection Operations¶

Once a connection has been established, it can be used to execute Commands. Commands are objects that represent operations that the database is to perform. This includes Queries, Update operations (Insert/Delete), and Transaction operations (Commit/Rollback). For the full list of operations, see the classes in the org.mulgara.query.operation package.

The list of operations is:

• AddAlias - adds a new namespace abbreviation to use when parsing queries. Returns a message String
• ApplyRules - run a Krule program on a graph. Returns a message String
• Backup - write the entire database to a file. Returns a message String
• Commit - commit the current transaction. Returns a message String
• CreateGraph - creates a new graph. Returns a message String
• Deletion - removes statements from a graph. Returns a message String
• DropGraph - removes a graph and all the statements it contains. Returns a message String
• ExecuteScript - sequentially runs a set of TQL operations in a file. Returns a message String
• Export - write the statements in a graph to a file. Returns a message String
• Help - returns a string containing help for TQL commands.
• Insertion - adds statements to a graph. Returns a message String
• Load - Loads a dataset from an RDF file into a graph. Returns the number of loaded statements
• NullOp - does nothing. Returns an empty String
• Quit - sets a client-side flag indicating that the client can quit. Returns a message String
• Restore - reads a backup file and loads it into this database. Returns a message string
• Rollback - rolls back the current transaction. Returns a message String
• SetAutoCommit - when set on, then any outstanding transactions are committed, and all subsequent operations are performed in their own transaction. When set off, a transaction is started. Returns a message String
• SetTime - sets a flag to let the client know if should record the time each operation takes to execute. Returns a message String
• SetUser - sets the username and credentials for a user (only used when a security module is present). Returns a message String

The remaining Commands are the 3 Query types:

• Query - executes a query (TQL or SPARQL) against a dataset. Returns an Answer object
• AskQuery - executes a SPARQL ASK query against a dataset. Returns a BooleanAnswer object
• ConstructQuery - returns a GraphAnswer object

Note that these operations correlate closely to the TQL commands that they implement.

Executing Operations¶

Different operations may return different result types. These types can be differentiated by executing the operation on the connection. For instance:

  Load load = new Load(sourceFileUri, graphUri, false);
  Long nrStatements = connection.execute(load);

However, in a general execution environment the type of the operation may not be known at compile time. In this case the operation can call execute with the connection as the argument. The return type will not be known ahead of time, but the operation can always be executed. For instance, the following executes a series of operations:

  List<Command> operations = ...;

  for (Command op: operations) {
    Object result = op.execute(connection);
    // process result
    if (result instanceof Integer) System.out.println("Loaded " + result + " statements");
    if (result instanceof String) System.out.println(result);
    if (result instanceof Answer) printAnswer((Answer)result);
  }

Other Operations¶

Connections have operations on them for setting and retrieving the "autocommit" state. This is the same state that is set by the SetAutoCommit operation listed above.

Connections also have methods to set the credentials on the connection. This offers the same functionality as the SetUser operation above. However, this operation does nothing when a security module is not present.

Cleaning Up¶

Connections should be closed when they are finished with. This allows the resources to be re-used by the ConnectionFactory.

If the resources owned by a connection need to be released (such as closing the underlying Session), then you should call the dispose() method on the Connection instead of close().

Example Code¶

The Connection API is used in the following sample tools:

• Sparql
• Tql