Project

General

Profile

UserAPI » History » Version 4

Paula Gearon, 05/15/2008 09:07 PM

1 3 Paula Gearon
= Connection API =
2
== Overview ==
3 1 Paula Gearon
Mulgara now supports a new interface called a `Connection`. This will be replacing the current `ItqlInterpreterBean` interface as the full suite of utilities becomes available.
4
5
The existing `ItqlInterpreterBean` interface provides a completely automated connection mechanism, based on the URLs of graphs referenced in TQL queries. While convenient, this has several undesirable effects:
6
* All queries issued to this interface must contain at least one URL for a graph on the server that will handle the query.
7
* Arbitrary graph names are not permitted. Graph names must follow a particular format, and will include the hostname of the server containing the graph.
8
* Queries against graphs must be changed when the server hosting the graph changes.
9
* Connections to a server cannot be cached.
10
* Distributed queries (queries where the requested data comes from more than one server) are sent to an arbitrary server and not necessarily the most desirable one.
11
* Query languages which use a default graph name (like [http://www.w3.org/TR/rdf-sparql-query/ SPARQL]) cannot identify a server if no graph names are given.
12
13
The `Connection` interface avoids these issues by establishing a link to a specified server. This link can be to a server running in the current process, over inter-process-communication (IPC) to a server running on the same machine, or across a network. Queries and commands can be sent along this link, and all operations will be performed by the server that has been connected to.
14
15
The `Connection` interface and its supporting classes are found in the `org.mulgara.connection` package.
16
17
== Connection Factory ==
18
While Connections can be created directly, the `ConnectionFactory` class attempts to manage connections to ensure that the correct type is created, and reduce network overhead. The connections returned by a `ConnectionFactory` are only managed by that factory, and will not interfere with connections from a separate factory instance.
19
20
`Connection`s can be established based on the URL of a database (in the form ''protocol''://''host''/''service'') or by wrapping a `Session` instance. The `Session` interface has existed in Mulgara for some time, and it may be more appropriate for existing code to use its internal `Session` instances to create new `Connection`s.
21
22
For the moment, the only supported protocol is ''rmi''. Other protocols, including ''http'' are expected shortly.
23
24
== Using a Connection ==
25 2 Paula Gearon
=== Commands ===
26 1 Paula Gearon
Once a `Connection` has been created, commands can be sent on it using the `execute` method. Alternatively, commands also have their own `execute` method that can be applied to a connection, with the same effect.
27
28
The following is an example of using a Connection to create a graph, and load a file into that graph:
29
{{{
30
#!java
31
    // define the server we want to connect to
32
    URI serverURI = new URI("rmi://localhost/server1");
33
    // define the file we want to load
34
    URI dataFile = new File("data.rdf").toURI();
35
    // define the name of the graph to load the data into
36
    URI myData = new URI("test:data");
37
38
    // Create a factory, and connect to the server
39
    ConnectionFactory factory = new ConnectionFactory();
40
    Connection connection = factory.newConnection(serverUri);
41
42
    // execute a CREATE command
43
    connection.execute(new CreateGraph(myData));
44
    // execute a LOAD command
45
    connection.execute(new Load(dataFile, myData, true));
46 2 Paula Gearon
47
    // cleaning up the connection allows the network resources to be re-used
48
    connection.close();
49
}}}
50
51
Executing a command returns a String containing a message related to the success of the command. If commands are kept, then it is also possible to retrieve the last message from a command with the `getResultMessage` method.
52
53
=== Queries ===
54
Queries are a type of command that return an `Answer` instead of a message string. Queries can be created using either the TQL or SPARQL parsers:
55
{{{
56
#!java
57
    // define the server we want to connect to
58
    URI serverURI = new URI("rmi://localhost/server1");
59
60
    // Create a factory, and connect to the server
61
    ConnectionFactory factory = new ConnectionFactory();
62
    Connection connection = factory.newConnection(serverUri);
63 1 Paula Gearon
64
    // Use a SPARQL query
65 3 Paula Gearon
    Query query = new SparqlInterpreter().parseQuery(
66
                  "SELECT * FROM <test:data> WHERE { ?s ?p ?o }");
67 2 Paula Gearon
    Answer answer = connection.execute(query);
68
69
    // display the result
70
    answer.beforeFirst();
71
    while (answer.next()) {
72
      System.out.print(" " + answer.getObject(0));
73
      System.out.print(" " + answer.getObject(1));
74
      System.out.println(" " + answer.getObject(2));
75
    }
76
    answer.close();
77 1 Paula Gearon
78
    connection.close();
79
}}}