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	dpavlin	237	/*
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