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;
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 worflow 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
38 public class Connection {
41 protected SWIGTYPE_p_ZOOM_connection_p zoomConnection;
42 //connection is initially closed
43 protected boolean closed = true;
44 private boolean disposed = false;
46 public enum QueryType {
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);
58 * Create new connection object without physically opening a connection to the
60 * @param host host name of the server
61 * @param port port of the server
63 public Connection(String host, int port) {
66 zoomConnection = yaz4jlib.ZOOM_connection_create(null);
69 public void finalize() {
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
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
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);
92 SWIGTYPE_p_ZOOM_resultset_p yazResultSet = yaz4jlib.ZOOM_connection_search(zoomConnection, yazQuery);
93 ZoomException err = ExceptionUtil.getError(zoomConnection, host,
96 yaz4jlib.ZOOM_resultset_destroy(yazResultSet);
97 yaz4jlib.ZOOM_query_destroy(yazQuery);
100 return new ResultSet(yazResultSet, this);
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
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);
116 yaz4jlib.ZOOM_scanset_destroy(yazScanSet);
119 ScanSet scanSet = new ScanSet(yazScanSet, this);
124 * Establishes a connection to the remote server.
125 * @throws ZoomException any (possibly network-level) errors that may occurr
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;
135 * Closes the connection.
137 public void close() {
138 yaz4jlib.ZOOM_connection_close(zoomConnection);
143 * Write option with a given name.
144 * @param name option name
145 * @param value option value
146 * @return connection (self) for chainability
148 public Connection option(String name, String value) {
149 yaz4jlib.ZOOM_connection_option_set(zoomConnection, name, value);
154 * Read option with a given name
155 * @param name option name
156 * @return option value
158 public String option(String name) {
159 return yaz4jlib.ZOOM_connection_option_get(zoomConnection, name);
163 * Same as option("preferredRecordSyntax")
164 * @return value of preferred record syntax
166 public String getSyntax() {
167 return option("preferredRecordSyntax");
171 * Same as option("preferredRecordSyntax", value)
172 * @param value value of preferred record syntax
174 public void setSyntax(String value) {
175 option("preferredRecordSyntax", value);
179 * Same as option("databaseName")
180 * @return value of databaseName
182 public String getDatabaseName() {
183 return option("databaseName");
187 * Same as option("databaseName", value)
188 * @param value value of databaseName
190 public void setDatabaseName(String value) {
191 option("databaseName", value);
195 * Same as option("user")
196 * @return value of user
198 public String getUsername() {
199 return option("user");
203 * Same as option("user", value)
204 * @param value value of user
206 public void setUsername(String value) {
207 option("user", value);
211 * Same as option("password")
212 * @return value of password
214 public String getPassword() {
215 return option("password");
219 * Same as option("password", value)
222 public void setPassword(String value) {
223 option("password", value);
231 yaz4jlib.ZOOM_connection_destroy(zoomConnection);
232 zoomConnection = null;