src/main/java/org/yaz4j/Connection.java

   1 package org.yaz4j;
   2
   3 import org.yaz4j.exception.ZoomException;
   4 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_connection_p;
   5 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_query_p;
   6 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_resultset_p;
   7 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_scanset_p;
   8 import org.yaz4j.jni.yaz4jlib;
   9
  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 worflow 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  * @author jakub
  37  */
  38 public class Connection {
  39     private String host;
  40     private int port;
  41     protected SWIGTYPE_p_ZOOM_connection_p zoomConnection;
  42     //connection is initially closed
  43     protected boolean closed = true;
  44     private boolean disposed = false;
  45
  46     public enum QueryType {
  47         CQLQuery, PrefixQuery
  48     };
  49
  50     static {
  51         // on Linux   'yaz4j' maps to 'libyaz4j.so' (i.e. 'lib' prefix & '.so'  extension)
  52         // on Windows 'yaz4j' maps to 'yaz4j.dll'   (i.e.                '.dll' extension)
  53         String libName = "yaz4j";
  54         System.loadLibrary(libName);
  55     }
  56
  57     /**
  58      * Create new connection object without physically opening a connection to the
  59      * remote server.
  60      * @param host host name of the server
  61      * @param port port of the server
  62      */
  63     public Connection(String host, int port) {
  64         this.host = host;
  65         this.port = port;
  66         zoomConnection = yaz4jlib.ZOOM_connection_create(null);
  67     }
  68
  69     public void finalize() {
  70         _dispose();
  71     }
  72
  73     /**
  74      * Performs a search operation (submits the query to the server, waits for
  75      * response and creates a new result set that allows to retrieve particular
  76      * results)
  77      * @param query search query
  78      * @param queryType type of the query (e.g RPN. CQL)
  79      * @return result set containing records (hits)
  80      * @throws ZoomException protocol or network-level error
  81      */
  82     public ResultSet search(String query, QueryType queryType) throws ZoomException {
  83       if (closed) throw new IllegalStateException("Connection is closed.");
  84       SWIGTYPE_p_ZOOM_query_p yazQuery = null;
  85       if (queryType == QueryType.CQLQuery) {
  86           yazQuery = yaz4jlib.ZOOM_query_create();
  87           yaz4jlib.ZOOM_query_cql(yazQuery, query);
  88       } else if (queryType == QueryType.PrefixQuery) {
  89           yazQuery = yaz4jlib.ZOOM_query_create();
  90           yaz4jlib.ZOOM_query_prefix(yazQuery, query);
  91       }
  92       SWIGTYPE_p_ZOOM_resultset_p yazResultSet = yaz4jlib.ZOOM_connection_search(zoomConnection, yazQuery);
  93       ZoomException err = ExceptionUtil.getError(zoomConnection, host,
  94         port);
  95       if (err != null) {
  96           yaz4jlib.ZOOM_resultset_destroy(yazResultSet);
  97           yaz4jlib.ZOOM_query_destroy(yazQuery);
  98           throw err;
  99       }
 100       return new ResultSet(yazResultSet, this);
 101     }
 102
 103     /**
 104      * Performs a scan operation (obtains a list of candidate search terms against
 105      * a particular access point)
 106      * @see <a href="http://zoom.z3950.org/api/zoom-1.4.html#3.2.7">ZOOM-API Scan</a>
 107      * @param query query for scanning
 108      * @return a scan set with the terms
 109      * @throws ZoomException a protocol or network-level error
 110      */
 111     public ScanSet scan(String query) throws ZoomException {
 112       if (closed) throw new IllegalStateException("Connection is closed.");
 113         SWIGTYPE_p_ZOOM_scanset_p yazScanSet = yaz4jlib.ZOOM_connection_scan(zoomConnection, query);
 114         ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
 115         if (err != null) {
 116             yaz4jlib.ZOOM_scanset_destroy(yazScanSet);
 117             throw err;
 118         }
 119         ScanSet scanSet = new ScanSet(yazScanSet, this);
 120         return scanSet;
 121     }
 122
 123     /**
 124      * Establishes a connection to the remote server.
 125      * @throws ZoomException any (possibly network-level) errors that may occurr
 126      */
 127     public void connect() throws ZoomException {
 128       yaz4jlib.ZOOM_connection_connect(zoomConnection, host, port);
 129       ZoomException err = ExceptionUtil.getError(zoomConnection, host, port);
 130       if (err != null) throw err;
 131       closed = false;
 132     }
 133
 134     /**
 135      * Closes the connection.
 136      */
 137     public void close() {
 138       yaz4jlib.ZOOM_connection_close(zoomConnection);
 139       closed = true;
 140     }
 141
 142     /**
 143      * Write option with a given name.
 144      * @param name option name
 145      * @param value option value
 146      * @return connection (self) for chainability
 147      */
 148     public Connection option(String name, String value) {
 149       yaz4jlib.ZOOM_connection_option_set(zoomConnection, name, value);
 150       return this;
 151     }
 152
 153     /**
 154      * Read option with a given name
 155      * @param name option name
 156      * @return option value
 157      */
 158     public String option(String name) {
 159       return yaz4jlib.ZOOM_connection_option_get(zoomConnection, name);
 160     }
 161
 162     /**
 163      * Same as option("preferredRecordSyntax")
 164      * @return value of preferred record syntax
 165      */
 166     public String getSyntax() {
 167         return option("preferredRecordSyntax");
 168     }
 169
 170     /**
 171      * Same as option("preferredRecordSyntax", value)
 172      * @param value value of preferred record syntax
 173      */
 174     public void setSyntax(String value) {
 175         option("preferredRecordSyntax", value);
 176     }
 177
 178     /**
 179      * Same as option("databaseName")
 180      * @return value of databaseName
 181      */
 182     public String getDatabaseName() {
 183         return option("databaseName");
 184     }
 185
 186     /**
 187      * Same as option("databaseName", value)
 188      * @param value value of databaseName
 189      */
 190     public void setDatabaseName(String value) {
 191         option("databaseName", value);
 192     }
 193
 194     /**
 195      * Same as option("user")
 196      * @return value of user
 197      */
 198     public String getUsername() {
 199         return option("user");
 200     }
 201
 202     /**
 203      * Same as option("user", value)
 204      * @param value value of user
 205      */
 206     public void setUsername(String value) {
 207         option("user", value);
 208     }
 209
 210     /**
 211      * Same as option("password")
 212      * @return value of password
 213      */
 214     public String getPassword() {
 215         return option("password");
 216     }
 217
 218     /**
 219      * Same as option("password", value)
 220      * @param value
 221      */
 222     public void setPassword(String value) {
 223         option("password", value);
 224     }
 225
 226     /**
 227      * INTERNAL, GC-ONLY
 228      */
 229     void _dispose() {
 230         if (!disposed) {
 231           yaz4jlib.ZOOM_connection_destroy(zoomConnection);
 232           zoomConnection = null;
 233           disposed = true;
 234         }
 235     }
 236 }