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 }