ae99d7cc5898feca0db0c16097ae3618cc0be76d
[yaz4j-moved-to-github.git] / src / main / java / org / yaz4j / Connection.java
1 package org.yaz4j;
2
3 import java.io.Closeable;
4 import org.yaz4j.exception.ZoomException;
5 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_connection_p;
6 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_query_p;
7 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_resultset_p;
8 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_scanset_p;
9 import org.yaz4j.jni.yaz4jlib;
10
11 /**
12  * Class representing an on-going communication with an IR server.
13  *
14  * Creating an instance of this class does not automatically connect (e.g open
15  * a socket) to the remote server as the programmer may want to specify options
16  * on the object before establishing the actual connection.
17  *
18  * The work-flow for synchronous (the only addressed) operation when using this
19  * class should be as follows (in pseudocode):
20  *
21  * <blockquote><pre>
22  *
23  * try {
24  *  c = new Connection(...)
25  *  //possibly set some options
26  *  c.connect //establishes connection
27  *  c.search //or other operation
28  *  //possibly retrieve records
29  * catch (ZoomException e) {
30  *  //handle any protocol- or network-level errors
31  * } finally {
32  *  c.close //close the socket
33  * }
34  *
35  * </pre></blockquote>
36  * @see <a href="http://www.indexdata.com/yaz/doc/zoom.html#zoom-connections">YAZ ZOOM Connection</a>
37  * @author jakub
38  */
39 public class Connection implements Closeable {
40
41   private String host;
42   private int port;
43   protected SWIGTYPE_p_ZOOM_connection_p zoomConnection;
44   //connection is initially closed
45   protected boolean closed = true;
46   private boolean disposed = false;
47
48   public enum QueryType {
49
50     CQLQuery, PrefixQuery
51   };
52
53   static {
54     // on Linux   'yaz4j' maps to 'libyaz4j.so' (i.e. 'lib' prefix & '.so'  extension)
55     // on Windows 'yaz4j' maps to 'yaz4j.dll'   (i.e.                '.dll' extension)
56     String libName = "yaz4j";
57     System.loadLibrary(libName);
58   }
59
60   /**
61    * Create new connection object without physically opening a connection to the
62    * remote server.
63    * @param host host name of the server
64    * @param port port of the server
65    */
66   public Connection(String host, int port) {
67     this.host = host;
68     this.port = port;
69     zoomConnection = yaz4jlib.ZOOM_connection_create(null);
70   }
71
72   public void finalize() {
73     _dispose();
74   }
75
76   /**
77    * Performs a search operation (submits the query to the server, waits for
78    * response and creates a new result set that allows to retrieve particular
79    * results)
80    * @deprecated Does not allow specifying sort criteria prior to search
81    * use {@link #search(org.yaz4j.Query) search(Query)} instead.
82    * @param query search query
83    * @param queryType type of the query (e.g RPN. CQL)
84    * @return result set containing records (hits)
85    * @throws ZoomException protocol or network-level error
86    */
87   @Deprecated
88   public ResultSet search(String query, QueryType queryType) throws
89     ZoomException {
90     if (closed) {
91       throw new IllegalStateException("Connection is closed.");
92     }
93     SWIGTYPE_p_ZOOM_query_p yazQuery = null;
94     if (queryType == QueryType.CQLQuery) {
95       yazQuery = yaz4jlib.ZOOM_query_create();
96       yaz4jlib.ZOOM_query_cql(yazQuery, query);
97     } else if (queryType == QueryType.PrefixQuery) {
98       yazQuery = yaz4jlib.ZOOM_query_create();
99       yaz4jlib.ZOOM_query_prefix(yazQuery, query);
100     }
101     SWIGTYPE_p_ZOOM_resultset_p yazResultSet = yaz4jlib.ZOOM_connection_search(
102       zoomConnection, yazQuery);
103     yaz4jlib.ZOOM_query_destroy(yazQuery);
104     ZoomException err = ExceptionUtil.getError(zoomConnection, host,
105       port);
106     if (err != null) {
107       yaz4jlib.ZOOM_resultset_destroy(yazResultSet);
108       throw err;
109     }
110     return new ResultSet(yazResultSet, this);
111   }
112   
113     /**
114    * Performs a search operation (submits the query to the server, waits for
115    * response and creates a new result set that allows to retrieve particular
116    * results). Sort criteria may be specified prior to the search, directly
117    * on the query object.
118    * @param query search query of any type supported by YAZ.
119    * @return result set containing records (hits)
120    * @throws ZoomException protocol or network-level error
121    */
122   public ResultSet search(Query query) throws ZoomException {
123     if (closed) {
124       throw new IllegalStateException("Connection is closed.");
125     }
126     SWIGTYPE_p_ZOOM_resultset_p yazResultSet = yaz4jlib.ZOOM_connection_search(
127       zoomConnection, query.query);
128     ZoomException err = ExceptionUtil.getError(zoomConnection, host,
129       port);
130     if (err != null) {
131       yaz4jlib.ZOOM_resultset_destroy(yazResultSet);
132       throw err;
133     }
134     return new ResultSet(yazResultSet, this);
135   }
136
137   /**
138    * Performs a scan operation (obtains a list of candidate search terms against
139    * a particular access point). 
140    * @deprecated Only allows PQF scan queries, use {@link #scan(org.yaz4j.Query) scan(Query)} instead
141    * @param query query for scanning
142    * @return a scan set with the terms
143    * @throws ZoomException a protocol or network-level error
144    */
145   @Deprecated
146   public ScanSet scan(String query) throws ZoomException {
147     if (closed) {
148       throw new IllegalStateException("Connection is closed.");
149     }
150     SWIGTYPE_p_ZOOM_scanset_p yazScanSet = yaz4jlib.ZOOM_connection_scan(
151       zoomConnection, query);
152     ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
153     if (err != null) {
154       yaz4jlib.ZOOM_scanset_destroy(yazScanSet);
155       throw err;
156     }
157     ScanSet scanSet = new ScanSet(yazScanSet, this);
158     return scanSet;
159   }
160   
161     /**
162    * Performs a scan operation (obtains a list of candidate search terms against
163    * a particular access point). Allows to use both CQL and PQF for Scan.
164    * @see <a href="http://www.indexdata.com/yaz/doc/zoom.scan.html">ZOOM-API Scan</a>
165    * @param query scan query of type supported by YAZ
166    * @return a scan set with the terms
167    * @throws ZoomException a protocol or network-level error
168    */
169   public ScanSet scan(Query query) throws ZoomException {
170     if (closed) {
171       throw new IllegalStateException("Connection is closed.");
172     }
173     SWIGTYPE_p_ZOOM_scanset_p yazScanSet = yaz4jlib.ZOOM_connection_scan1(
174       zoomConnection, query.query);
175     ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
176     if (err != null) {
177       yaz4jlib.ZOOM_scanset_destroy(yazScanSet);
178       throw err;
179     }
180     ScanSet scanSet = new ScanSet(yazScanSet, this);
181     return scanSet;
182   }
183
184   /**
185    * Establishes a connection to the remote server.
186    * @throws ZoomException any (possibly network-level) errors that may occurr
187    */
188   public void connect() throws ZoomException {
189     yaz4jlib.ZOOM_connection_connect(zoomConnection, host, port);
190     ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
191     if (err != null) {
192       throw err;
193     }
194     closed = false;
195   }
196
197   /**
198    * Closes the connection.
199    */
200   public void close() {
201     yaz4jlib.ZOOM_connection_close(zoomConnection);
202     closed = true;
203   }
204   
205   /**
206    * Return exception type from current connection
207    *
208    * @return null if no error
209    */
210   ZoomException getZoomException() {
211     ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
212     return err;
213   }
214
215   /**
216    * Write option with a given name.
217    * @param name option name
218    * @param value option value
219    * @return connection (self) for chainability
220    */
221   public Connection option(String name, String value) {
222     yaz4jlib.ZOOM_connection_option_set(zoomConnection, name, value);
223     return this;
224   }
225
226   /**
227    * Read option with a given name
228    * @param name option name
229    * @return option value
230    */
231   public String option(String name) {
232     return yaz4jlib.ZOOM_connection_option_get(zoomConnection, name);
233   }
234
235   /**
236    * Same as option("preferredRecordSyntax")
237    * @return value of preferred record syntax
238    */
239   public String getSyntax() {
240     return option("preferredRecordSyntax");
241   }
242
243   /**
244    * Same as option("preferredRecordSyntax", value)
245    * @param value value of preferred record syntax
246    */
247   public void setSyntax(String value) {
248     option("preferredRecordSyntax", value);
249   }
250
251   /**
252    * Same as option("databaseName")
253    * @return value of databaseName
254    */
255   public String getDatabaseName() {
256     return option("databaseName");
257   }
258
259   /**
260    * Same as option("databaseName", value)
261    * @param value value of databaseName
262    */
263   public void setDatabaseName(String value) {
264     option("databaseName", value);
265   }
266
267   /**
268    * Same as option("user")
269    * @return value of user
270    */
271   public String getUsername() {
272     return option("user");
273   }
274
275   /**
276    * Same as option("user", value)
277    * @param value value of user
278    */
279   public void setUsername(String value) {
280     option("user", value);
281   }
282
283   /**
284    * Same as option("password")
285    * @return value of password
286    */
287   public String getPassword() {
288     return option("password");
289   }
290
291   /**
292    * Same as option("password", value)
293    * @param value
294    */
295   public void setPassword(String value) {
296     option("password", value);
297   }
298
299   /**
300    * INTERNAL, GC-ONLY
301    */
302   void _dispose() {
303     if (!disposed) {
304       yaz4jlib.ZOOM_connection_destroy(zoomConnection);
305       zoomConnection = null;
306       disposed = true;
307     }
308   }
309 }