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;
12 * Class representing an on-going communication with an IR server.
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.
18 * The work-flow for synchronous (the only addressed) operation when using this
19 * class should be as follows (in pseudocode):
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
32 * c.close //close the socket
36 * @see <a href="http://www.indexdata.com/yaz/doc/zoom.html#zoom-connections">YAZ ZOOM Connection</a>
39 public class Connection implements Closeable {
40 protected final String host;
41 protected final int port;
42 protected SWIGTYPE_p_ZOOM_connection_p zoomConnection;
43 //connection is initially closed
44 protected boolean closed = true;
45 private boolean disposed = false;
47 public enum QueryType {
53 // on Linux 'yaz4j' maps to 'libyaz4j.so' (i.e. 'lib' prefix & '.so' extension)
54 // on Windows 'yaz4j' maps to 'yaz4j.dll' (i.e. '.dll' extension)
55 String libName = "yaz4j";
56 System.loadLibrary(libName);
60 * Create new connection object without physically opening a connection to the
62 * @param host host name of the server
63 * @param port port of the server
65 public Connection(String host, int port) {
67 throw new NullPointerException("host cannot be null");
70 zoomConnection = yaz4jlib.ZOOM_connection_create(null);
73 public void finalize() {
78 * Performs a search operation (submits the query to the server, waits for
79 * response and creates a new result set that allows to retrieve particular
81 * @deprecated Does not allow specifying sort criteria prior to search
82 * use {@link #search(org.yaz4j.Query) search(Query)} instead.
83 * @param query search query
84 * @param queryType type of the query (e.g RPN. CQL)
85 * @return result set containing records (hits)
86 * @throws ZoomException protocol or network-level error
89 public ResultSet search(String query, QueryType queryType) throws
92 throw new NullPointerException("query cannot be null");
93 if (queryType == null)
94 throw new NullPointerException("queryType cannot be null");
96 throw new IllegalStateException("Connection is closed.");
97 SWIGTYPE_p_ZOOM_query_p yazQuery = null;
98 if (queryType == QueryType.CQLQuery) {
99 yazQuery = yaz4jlib.ZOOM_query_create();
100 yaz4jlib.ZOOM_query_cql(yazQuery, query);
101 } else if (queryType == QueryType.PrefixQuery) {
102 yazQuery = yaz4jlib.ZOOM_query_create();
103 yaz4jlib.ZOOM_query_prefix(yazQuery, query);
105 SWIGTYPE_p_ZOOM_resultset_p yazResultSet = yaz4jlib.ZOOM_connection_search(
106 zoomConnection, yazQuery);
107 yaz4jlib.ZOOM_query_destroy(yazQuery);
108 ZoomException err = ExceptionUtil.getError(zoomConnection, host,
111 yaz4jlib.ZOOM_resultset_destroy(yazResultSet);
114 return new ResultSet(yazResultSet, this);
118 * Performs a search operation (submits the query to the server, waits for
119 * response and creates a new result set that allows to retrieve particular
120 * results). Sort criteria may be specified prior to the search, directly
121 * on the query object.
122 * @param query search query of any type supported by YAZ.
123 * @return result set containing records (hits)
124 * @throws ZoomException protocol or network-level error
126 public ResultSet search(Query query) throws ZoomException {
128 throw new NullPointerException("query cannot be null");
130 throw new IllegalStateException("Connection is closed.");
131 SWIGTYPE_p_ZOOM_resultset_p yazResultSet = yaz4jlib.ZOOM_connection_search(
132 zoomConnection, query.query);
133 ZoomException err = ExceptionUtil.getError(zoomConnection, host,
136 yaz4jlib.ZOOM_resultset_destroy(yazResultSet);
139 return new ResultSet(yazResultSet, this);
145 * Performs a scan operation (obtains a list of candidate search terms against
146 * a particular access point).
147 * @deprecated Only allows PQF scan queries, use {@link #scan(org.yaz4j.Query) scan(Query)} instead
148 * @param query query for scanning
149 * @return a scan set with the terms
150 * @throws ZoomException a protocol or network-level error
153 public ScanSet scan(String query) throws ZoomException {
155 throw new NullPointerException("query cannot be null");
157 throw new IllegalStateException("Connection is closed.");
158 SWIGTYPE_p_ZOOM_scanset_p yazScanSet = yaz4jlib.ZOOM_connection_scan(
159 zoomConnection, query);
160 ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
162 yaz4jlib.ZOOM_scanset_destroy(yazScanSet);
165 ScanSet scanSet = new ScanSet(yazScanSet, this);
170 * Performs a scan operation (obtains a list of candidate search terms against
171 * a particular access point). Allows to use both CQL and PQF for Scan.
172 * @see <a href="http://www.indexdata.com/yaz/doc/zoom.scan.html">ZOOM-API Scan</a>
173 * @param query scan query of type supported by YAZ
174 * @return a scan set with the terms
175 * @throws ZoomException a protocol or network-level error
177 public ScanSet scan(Query query) throws ZoomException {
179 throw new NullPointerException("query cannot be null");
181 throw new IllegalStateException("Connection is closed.");
182 SWIGTYPE_p_ZOOM_scanset_p yazScanSet = yaz4jlib.ZOOM_connection_scan1(
183 zoomConnection, query.query);
184 ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
186 yaz4jlib.ZOOM_scanset_destroy(yazScanSet);
189 ScanSet scanSet = new ScanSet(yazScanSet, this);
194 * Establishes a connection to the remote server.
195 * @throws ZoomException any (possibly network-level) errors that may occurr
197 public void connect() throws ZoomException {
198 yaz4jlib.ZOOM_connection_connect(zoomConnection, host, port);
199 ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
207 * Closes the connection.
210 public void close() {
211 yaz4jlib.ZOOM_connection_close(zoomConnection);
216 * Return exception type from current connection
218 * @return null if no error
220 ZoomException getZoomException() {
221 ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
226 * Write option with a given name.
227 * @param name option name
228 * @param value option value
229 * @return connection (self) for chainability
231 public Connection option(String name, String value) {
233 throw new NullPointerException("option name cannot be null");
234 yaz4jlib.ZOOM_connection_option_set(zoomConnection, name, value);
239 * Read option with a given name
240 * @param name option name
241 * @return option value
243 public String option(String name) {
245 throw new NullPointerException("option name cannot be null");
246 return yaz4jlib.ZOOM_connection_option_get(zoomConnection, name);
250 * Same as option("preferredRecordSyntax")
251 * @return value of preferred record syntax
253 public String getSyntax() {
254 return option("preferredRecordSyntax");
258 * Same as option("preferredRecordSyntax", value)
259 * @param value value of preferred record syntax
261 public void setSyntax(String value) {
262 option("preferredRecordSyntax", value);
266 * Same as option("databaseName")
267 * @return value of databaseName
269 public String getDatabaseName() {
270 return option("databaseName");
274 * Same as option("databaseName", value)
275 * @param value value of databaseName
277 public void setDatabaseName(String value) {
278 option("databaseName", value);
282 * Same as option("user")
283 * @return value of user
285 public String getUsername() {
286 return option("user");
290 * Same as option("user", value)
291 * @param value value of user
293 public void setUsername(String value) {
294 option("user", value);
298 * Same as option("password")
299 * @return value of password
301 public String getPassword() {
302 return option("password");
306 * Same as option("password", value)
309 public void setPassword(String value) {
310 option("password", value);
318 yaz4jlib.ZOOM_connection_destroy(zoomConnection);
319 zoomConnection = null;