UserAPI » History » Version 3
Paula Gearon, 05/15/2008 09:05 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 | // cleaning up the connection allows the network resources to be re-used |
||
79 | connection.close(); |
||
80 | }}} |