org/openisis/Db.java

/*
        openisis - an open implementation of the CDS/ISIS database
        Version 0.8.x (patchlevel see file Version)
        Copyright (C) 2001-2003 by Erik Grziwotz, erik@openisis.org

        This library is free software; you can redistribute it and/or
        modify it under the terms of the GNU Lesser General Public
        License as published by the Free Software Foundation; either
        version 2.1 of the License, or (at your option) any later version.

        This library is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        Lesser General Public License for more details.

        You should have received a copy of the GNU Lesser General Public
        License along with this library; if not, write to the Free Software
        Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

        see README for more information
EOH */


package org.openisis;

import java.io.IOException;
import java.util.Iterator;
import java.util.Map;
import java.util.HashMap;


/**
        This class represents an isis db.
        The actual implementation is done in derived classes.
<p>
        $Id: Db.java,v 1.6 2003/04/08 00:20:53 kripke Exp $
        @version $Revision: 1.6 $
        @author  $Author: kripke $
*/
public abstract class Db {

        /** the default encoding.
         *      the constant String value is "ISO-8859-1".
        */
        public static final String DEFAULT_ENCODING = "ISO-8859-1";

        /* standard empty String returned by several methods */
        public static final String EMPTY = "";

        /** index scan key equal */
        public static final int QRY_KEYEQ = 0;
        /** index scan key prefix */
        public static final int QRY_KEYPF = 1;
        public static final int PREFIX = QRY_KEYPF; // legacy alias
        /** index scan key auto (checks for '$') */
        public static final int QRY_KEYAT = 2;
        /** fulltext scan for equal */
        public static final int QRY_SCANE = 64;
        /** fulltext scan for contains */
        public static final int QRY_SCANC = 65;
        /** query expression with simple left-to-right binding */
        public static final int QRY_SIMPLE = 128;
        /** query expression with proper binding using precedence, () */
        public static final int QRY_PROPER = 129;

        /** field v: heading mode */
        public static final int MHL = 0x10000;
        /** field v: data flag (no effect w/o heading) */
        public static final int MD  = 0x20000;
        /** field v: data mode (includes heading flag) */
        public static final int MDL = 0x30000;
        /** field v: uppercase mode flag */
        public static final int MXU = 0x40000;
        /** field v: uppercase heading mode */
        public static final int MHU = 0x50000;
        /** field v: uppercase data mode */
        public static final int MDU = 0x70000;
        /** field v: index formatting flag */
        public static final int MI  = 0x80000;

        /** field v: 16bit UNICODE HTML. HTML-entities are escaped. */
        public static final int HTU = 0x100000;
        /** field v: 8bit ISO-8859-1 HTML.
                HTML-entities and all chars greater than 255 are escaped.
        */
        public static final int HTI = 0x300000;
        /** field v: 7bit ASCII HTML.
                HTML-entities and all chars greater than 127 are escaped.
        */
        public static final int HTA = 0x700000;

        /** rec v: repeated prefix plus operator (not on 1st occ) */
        public static final int PP = 0x2000000;
        /** rec v: repeated suffix plus operator (not on last occ) */
        public static final int PS = 0x1000000;
        /** rec v: dummy presence selector Dn */
        public static final int DS = 0x4000000;
        /** rec v: dummy absence selector Nn */
        public static final int NS = 0x8000000;

        /** rec v: occurence range up to last occ */
        public static final int LOCC = 0xffff << 16;

        static final Map _dbs = new HashMap();


        /** open an isis database.
        The following options are supported as text-style parameters:
        <ul>
        <li>-db &lt;name&gt;<br>
                basename of database. same as param dbname.
        </li>
        <li>-dbpath &lt;path&gt;<br>
                path to database. usefull when opening secondary indexes
                or other files whose names are not based on the db basename.
        </li>
        <li>-v &lt;level&gt;<br>
                set verbosity level
        </li>
        <li>-encoding &lt;enc&gt;<br>
                select encoding used in db bytes. default is DEFAULT_ENCODING.
        </li>
        <li>-puredb<br>
                select pure java implementation.
                by default the NativeDb is used.
        </li>
        </ul>
        @param dbname basename of database.
                the dbhome arg, if given, will be prepended, and the ISIS file
                extensions appended to build the actual filename.
                Therefore, depending on the value of dbhome and location
                of files, this may need to include a path.
                db may be <code>null</code>, if argv includes a dbname arg.
        @param argv array of names and values.
                May be <code>null</code>.
                argv contains parameter names, which may be prefixed
                by a dash '-'. Depending on the actual parameter, the next
                string may or must contain a corresponding parameter value.
                An optional parameter value may be omitted, if at end of
                argv or the next name is prefixed with a dash.
                To avoid ambiguity, values never start with a dash.
                See above for a list of supported parameter names.
                Unrecognized parameter names are ignored.
        @return a new Db (unless some RuntimeException is thrown)
        @throws IoException especially FileNotFoundExceptiond
                and UnsupportedEncodingException
        */
        public static synchronized Db open ( String dbname, String[] args )
                throws IOException
        {
                String enc = DEFAULT_ENCODING;
                boolean usePureDb = false;
                Db db = (Db) _dbs.get( dbname );
                if ( null != db )
                        return db;
                if ( null != args )
                        for ( int i=0; i<args.length; i++ )
                                if ( "-encoding".equals( args[i] ) && i < args.length-1 ) {
                                        // if this Encoding gives UnsupportedEncodingException,
                                        // let it go off now
                                        byte b[] = new byte[1];
                                        b[0] = (byte)'A';
                                        new String( b, args[i+1] );
                                        enc =  args[i+1];
                                } else if ( "-puredb".equals( args[i] ) ) {
                                        // usePureDb = true;
                                        System.err.println( "sorry, -puredb not yet implemented" );
                                }
                db = // usePureDb ? (Db) new PureDb( enc, dbname, args ) : (Db)
                        new NativeDb( enc, dbname, args );
                // System.err.println( "Db.open('"+dbname+"'): "+db );
                _dbs.put( dbname, db );
                return db;
        }       // open


        public static int[] AND ( int[] set, int[] nset ) {
                int[] aset = new int[ // minimum
                        set.length < nset.length ? set.length : nset.length ];
                int a=0, s=0, n=0;
                while ( a<aset.length && s<set.length && n<nset.length ) {
                        if ( set[s] == nset[n] ) {
                                aset[a++] = set[s++];
                                n++;
                        } else if ( set[s] < nset[n] )
                                s++;
                        else
                                n++;
                }
                set = new int[a];
                System.arraycopy( aset, 0, set, 0, set.length );
                return set;
        }       // AND


        //
        //      so far for the statics
        //

        /** encoding used for records in this db.
         *      NOTE that String args are not converted according to this encoding,
         *      but rather are passed as Java UTF-8, so you better stick to 7 bits.
        */
        public final String encoding;

        protected Db ( String enc ) {
                encoding = enc;
        }


        /**
        read a cooked row.
        @param rowid the mfn
        @return a Rec or null, if row not available.
        */
        public abstract Rec readRow ( int rowid );

        /**
        write a cooked row.
        @param row the Rec to be written
        @return 0 if write succeeded, else a negative error code
        */
        public abstract short writeRow ( Rec rec );

        /**
        write a cooked row together with index information.
        @param row the Rec to be written
        @return 0 on success else a negative error code
        */
        public abstract short writeXRow ( Rec rec, Rec idx );

        /**
                read the first row with rowid &gt;= given rowid
                and containing txt in subfield tag (any, if 0).
                @param rowid the mfn
                @return a Rec or null, if row not available.
        */
        public abstract Rec scanRow ( int rowid, int tag, String txt );

        /**
                read the array of rowids matching key.
                @param key key to look for
                @param mode one of the QRY_ constants above.
                        may be ored with a tag&lt;&lt;16 to limit search to that field
        */
        public abstract int[] search ( String key, int mode );

        public abstract Iterator terms ( String prefix );

}       // Db
1	/*
2	openisis - an open implementation of the CDS/ISIS database
3	Version 0.8.x (patchlevel see file Version)
4	Copyright (C) 2001-2003 by Erik Grziwotz, erik@openisis.org
5
6	This library is free software; you can redistribute it and/or
7	modify it under the terms of the GNU Lesser General Public
8	License as published by the Free Software Foundation; either
9	version 2.1 of the License, or (at your option) any later version.
10
11	This library is distributed in the hope that it will be useful,
12	but WITHOUT ANY WARRANTY; without even the implied warranty of
13	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14	Lesser General Public License for more details.
15
16	You should have received a copy of the GNU Lesser General Public
17	License along with this library; if not, write to the Free Software
18	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19
20	see README for more information
21	EOH */
22
23
24	package org.openisis;
25
26	import java.io.IOException;
27	import java.util.Iterator;
28	import java.util.Map;
29	import java.util.HashMap;
30
31
32	/**
33	This class represents an isis db.
34	The actual implementation is done in derived classes.
35	<p>
36	$Id: Db.java,v 1.6 2003/04/08 00:20:53 kripke Exp $
37	@version $Revision: 1.6 $
38	@author $Author: kripke $
39	*/
40	public abstract class Db {
41
42	/** the default encoding.
43	* the constant String value is "ISO-8859-1".
44	*/
45	public static final String DEFAULT_ENCODING = "ISO-8859-1";
46
47	/* standard empty String returned by several methods */
48	public static final String EMPTY = "";
49
50	/** index scan key equal */
51	public static final int QRY_KEYEQ = 0;
52	/** index scan key prefix */
53	public static final int QRY_KEYPF = 1;
54	public static final int PREFIX = QRY_KEYPF; // legacy alias
55	/** index scan key auto (checks for '$') */
56	public static final int QRY_KEYAT = 2;
57	/** fulltext scan for equal */
58	public static final int QRY_SCANE = 64;
59	/** fulltext scan for contains */
60	public static final int QRY_SCANC = 65;
61	/** query expression with simple left-to-right binding */
62	public static final int QRY_SIMPLE = 128;
63	/** query expression with proper binding using precedence, () */
64	public static final int QRY_PROPER = 129;
65
66	/** field v: heading mode */
67	public static final int MHL = 0x10000;
68	/** field v: data flag (no effect w/o heading) */
69	public static final int MD = 0x20000;
70	/** field v: data mode (includes heading flag) */
71	public static final int MDL = 0x30000;
72	/** field v: uppercase mode flag */
73	public static final int MXU = 0x40000;
74	/** field v: uppercase heading mode */
75	public static final int MHU = 0x50000;
76	/** field v: uppercase data mode */
77	public static final int MDU = 0x70000;
78	/** field v: index formatting flag */
79	public static final int MI = 0x80000;
80
81	/** field v: 16bit UNICODE HTML. HTML-entities are escaped. */
82	public static final int HTU = 0x100000;
83	/** field v: 8bit ISO-8859-1 HTML.
84	HTML-entities and all chars greater than 255 are escaped.
85	*/
86	public static final int HTI = 0x300000;
87	/** field v: 7bit ASCII HTML.
88	HTML-entities and all chars greater than 127 are escaped.
89	*/
90	public static final int HTA = 0x700000;
91
92	/** rec v: repeated prefix plus operator (not on 1st occ) */
93	public static final int PP = 0x2000000;
94	/** rec v: repeated suffix plus operator (not on last occ) */
95	public static final int PS = 0x1000000;
96	/** rec v: dummy presence selector Dn */
97	public static final int DS = 0x4000000;
98	/** rec v: dummy absence selector Nn */
99	public static final int NS = 0x8000000;
100
101	/** rec v: occurence range up to last occ */
102	public static final int LOCC = 0xffff << 16;
103
104	static final Map _dbs = new HashMap();
105
106
107	/** open an isis database.
108	The following options are supported as text-style parameters:
109	<ul>
110	<li>-db <name><br>
111	basename of database. same as param dbname.
112	</li>
113	<li>-dbpath <path><br>
114	path to database. usefull when opening secondary indexes
115	or other files whose names are not based on the db basename.
116	</li>
117	<li>-v <level><br>
118	set verbosity level
119	</li>
120	<li>-encoding <enc><br>
121	select encoding used in db bytes. default is DEFAULT_ENCODING.
122	</li>
123	<li>-puredb<br>
124	select pure java implementation.
125	by default the NativeDb is used.
126	</li>
127	</ul>
128	@param dbname basename of database.
129	the dbhome arg, if given, will be prepended, and the ISIS file
130	extensions appended to build the actual filename.
131	Therefore, depending on the value of dbhome and location
132	of files, this may need to include a path.
133	db may be <code>null</code>, if argv includes a dbname arg.
134	@param argv array of names and values.
135	May be <code>null</code>.
136	argv contains parameter names, which may be prefixed
137	by a dash '-'. Depending on the actual parameter, the next
138	string may or must contain a corresponding parameter value.
139	An optional parameter value may be omitted, if at end of
140	argv or the next name is prefixed with a dash.
141	To avoid ambiguity, values never start with a dash.
142	See above for a list of supported parameter names.
143	Unrecognized parameter names are ignored.
144	@return a new Db (unless some RuntimeException is thrown)
145	@throws IoException especially FileNotFoundExceptiond
146	and UnsupportedEncodingException
147	*/
148	public static synchronized Db open ( String dbname, String[] args )
149	throws IOException
150	{
151	String enc = DEFAULT_ENCODING;
152	boolean usePureDb = false;
153	Db db = (Db) _dbs.get( dbname );
154	if ( null != db )
155	return db;
156	if ( null != args )
157	for ( int i=0; i<args.length; i++ )
158	if ( "-encoding".equals( args[i] ) && i < args.length-1 ) {
159	// if this Encoding gives UnsupportedEncodingException,
160	// let it go off now
161	byte b[] = new byte[1];
162	b[0] = (byte)'A';
163	new String( b, args[i+1] );
164	enc = args[i+1];
165	} else if ( "-puredb".equals( args[i] ) ) {
166	// usePureDb = true;
167	System.err.println( "sorry, -puredb not yet implemented" );
168	}
169	db = // usePureDb ? (Db) new PureDb( enc, dbname, args ) : (Db)
170	new NativeDb( enc, dbname, args );
171	// System.err.println( "Db.open('"+dbname+"'): "+db );
172	_dbs.put( dbname, db );
173	return db;
174	} // open
175
176
177	public static int[] AND ( int[] set, int[] nset ) {
178	int[] aset = new int[ // minimum
179	set.length < nset.length ? set.length : nset.length ];
180	int a=0, s=0, n=0;
181	while ( a<aset.length && s<set.length && n<nset.length ) {
182	if ( set[s] == nset[n] ) {
183	aset[a++] = set[s++];
184	n++;
185	} else if ( set[s] < nset[n] )
186	s++;
187	else
188	n++;
189	}
190	set = new int[a];
191	System.arraycopy( aset, 0, set, 0, set.length );
192	return set;
193	} // AND
194
195
196	//
197	// so far for the statics
198	//
199
200	/** encoding used for records in this db.
201	* NOTE that String args are not converted according to this encoding,
202	* but rather are passed as Java UTF-8, so you better stick to 7 bits.
203	*/
204	public final String encoding;
205
206	protected Db ( String enc ) {
207	encoding = enc;
208	}
209
210
211	/**
212	read a cooked row.
213	@param rowid the mfn
214	@return a Rec or null, if row not available.
215	*/
216	public abstract Rec readRow ( int rowid );
217
218	/**
219	write a cooked row.
220	@param row the Rec to be written
221	@return 0 if write succeeded, else a negative error code
222	*/
223	public abstract short writeRow ( Rec rec );
224
225	/**
226	write a cooked row together with index information.
227	@param row the Rec to be written
228	@return 0 on success else a negative error code
229	*/
230	public abstract short writeXRow ( Rec rec, Rec idx );
231
232	/**
233	read the first row with rowid >= given rowid
234	and containing txt in subfield tag (any, if 0).
235	@param rowid the mfn
236	@return a Rec or null, if row not available.
237	*/
238	public abstract Rec scanRow ( int rowid, int tag, String txt );
239
240	/**
241	read the array of rowids matching key.
242	@param key key to look for
243	@param mode one of the QRY_ constants above.
244	may be ored with a tag<<16 to limit search to that field
245	*/
246	public abstract int[] search ( String key, int mode );
247
248	public abstract Iterator terms ( String prefix );
249
250	} // Db