gate.persist
Class OracleDataStore

java.lang.Object
  |
  +--gate.util.AbstractFeatureBearer
        |
        +--gate.persist.JDBCDataStore
              |
              +--gate.persist.OracleDataStore
All Implemented Interfaces:
CreoleListener, DatabaseDataStore, DataStore, EventListener, FeatureBearer, NameBearer, Serializable

public class OracleDataStore
extends JDBCDataStore

See Also:
Serialized Form

Nested Class Summary
private  class OracleDataStore.Feature
           
private  class OracleDataStore.RestrictionComepator
           
 
Field Summary
private static boolean DEBUG
          Debug flag
private static String DS_COMMENT
          Name of this resource
private static String DS_ICON_NAME
          the icon for this resource
private static int INTERNAL_BUFFER_SIZE
          read buffer size (for reading CLOBs)
private static int ORACLE_FALSE
          "false" value for Oracle (supports no boolean type)
private static int ORACLE_TRUE
          "true" value for Oracle (supports no boolean type)
private static int ORACLE_VARCHAR_LIMIT_BYTES
          the size in bytes if varchar2 column in Oracle when a String is stored in Oracle it may be too long for a varchar2 value, and then CLOB will be used Note that the limit is in bytes, not in characters, so in the worst case this will limit the string to 4000/3 characters
private static int ORACLE_VARCHAR_MAX_SYMBOLS
          maximum number of characters per string stored as varchar2 if longer then stored as CLOB
private static int UTF_BYTES_PER_CHAR_MAX
          maximum number of bytes that represent a char in UTF8 database
private static int VARRAY_SIZE
          size of the Oracle varrays used for bulc inserts
 
Fields inherited from class gate.persist.JDBCDataStore
ac, datastoreComment, dbSchema, dbType, dependentResources, iconName, jdbcConn, name, session
 
Fields inherited from class gate.util.AbstractFeatureBearer
features
 
Fields inherited from interface gate.DataStore
DATASTORE_FEATURE_NAME, LR_ID_FEATURE_NAME
 
Constructor Summary
OracleDataStore()
          default constructor - just call the super constructor (may change in the future)
 
Method Summary
private  Long _createFeature(Long entityID, int entityType, String key, Object value, int valueType, CallableStatement stmt)
          creates a feature of the specified type/value/valueType/key for the specified entity Entity is one of: LR, Annotation Value types are: boolean, int, long, string, float, Object
private  void _createFeatureBulk(Vector features, CallableStatement stmt, oracle.sql.ArrayDescriptor adNumber, oracle.sql.ArrayDescriptor adString)
          creates a feature of the specified type/value/valueType/key for the specified entity Entity is one of: LR, Annotation Value types are: boolean, int, long, string, float, Object
private  boolean _lockLr(Long lrID)
          helper for lockLR() never call directly
protected  void _syncDocumentContent(Document doc)
          helper for sync() - never call directly
protected  void _syncDocumentHeader(Document doc)
          helper for sync() - never call directly
protected  void _syncFeatures(LanguageResource lr)
          helper for sync() - never call directly
protected  void _syncLR(LanguageResource lr)
          helper for sync() NEVER call directly
protected  void _syncRemovedDocumentsFromCorpus(List docLRIDs, Long corpLRID)
          helper for sync() - never call directly
private  void _updateFeatureLOB(Long featID, Object value, int valueType)
          updates the value of a feature where the value is string (>4000 bytes, stored as CLOB) or Object (stored as BLOB)
protected  void addDocumentToCorpus(Long docID, Long corpID)
          adds document to corpus in the database if the document is already part of the corpus nothing changes
protected  boolean canAccessLR(Long lrID, int mode)
          Checks if the user (identified by the sessionID) has some access (read/write) to the LR
 void close()
          Close the data store.
 void create()
          Create a new data store.
protected  void createAnnotationSet(Long lrID, AnnotationSet aset)
          creates an entry for annotation set in the database
protected  Long createDoc(Long _lrID, URL _docURL, String _docEncoding, Long _docStartOffset, Long _docEndOffset, Boolean _docIsMarkupAware, Long _corpusID)
          helper for adopt never call directly
private  void createFeature(Long entityID, int entityType, String key, Object value, CallableStatement stmt)
          creates a feature with the specified type/key/value for the specified entity entitties are either LRs ot Annotations valid values are: boolean, int, long, string, float, Object, boolean List, int List, long List, string List, float List, Object List
protected  void createFeatures(Long entityID, int entityType, FeatureMap features)
          helper metod iterates a FeatureMap and creates all its features in the database
protected  void createFeaturesBulk(Long entityID, int entityType, FeatureMap features)
          helper metod iterates a FeatureMap and creates all its features in the database since it uses Oracle VARRAYs the roundtrips between the client and the server are minimized make sure the two types STRING_ARRAY and INT_ARRAY have the same name in the PL/SQL files also when referencing the types always use the schema owner in upper case because the jdbc driver is buggy (see MetaLink note if u care)
protected  Long createLR(String lrType, String lrName, SecurityInfo si, Long lrParentID)
          helper for adopt() never call directly
protected  void deleteCorpus(Long lrId)
          helper method for delete() never call it directly beause proper events will not be fired
protected  void deleteDocument(Long lrId)
          helper method for delete() never call it directly beause proper events will not be fired
 boolean equals(Object obj)
          checks if two databases are identical
 List findDocIdsByAnn(List constraints, int limitcount)
           
 List findLrIds(List constraints)
          Get a list of LRs that satisfy some set or restrictions
 List findLrIds(List constraints, String lrType)
          Get a list of LRs IDs that satisfy some set or restrictions and are of a particular type
 List findLrIds(List constraints, String lrType, List orderByConstraints, int limitcount)
          Get a list of LRs IDs that satisfy some set or restrictions and are of a particular type
private  boolean fitsInVarchar2(String s)
          checks if a String should be stores as VARCHAR2 or CLOB because the VARCHAR2 in Oracle is limited to 4000 bytes, not all the strings fit there.
private  String getEndPartOfJoin(List orderByFilter, String lrType, Vector sqlValues)
           
private  String getIntersectionPart(List filter, Vector sqlValues)
           
private  String getJoinQuery(List orderByFilter, Vector sqlValues)
           
 long getLrsCount(List constraints, String lrType)
          Return count of LRs which matches the constraints.
private  String getNumberExpresion(Restriction restr, Vector sqlValues)
           
private  String getRestrictionPartOfQuery(List list, Vector sqlValues)
           
private  String getSQLQuery(List filter, String lrType, boolean count, List orderByFilter, int limitcount, Vector sqlValues)
           
private  String getSQLQueryAnn(List constraints, int limitcount, Vector sqlValues)
           
 String getStorageUrl()
          Get the URL for the underlying storage mechanism.
 boolean isAutoSaving()
          Get the autosaving behaviour of the LR.
 boolean lockLr(LanguageResource lr)
          Try to acquire exlusive lock on a resource from the persistent store.
private  Vector normalizeFeature(Long entityID, int entityType, String key, Object value)
          splits complex features (Lists) into a vector of Feature entries each entry contains the entity id, entity type, feature key feature value value type
 void open()
          Open a connection to the data store.
static Object readBLOB(Blob src)
          reads the content of the specified BLOB object and returns the object contained.
static void readCLOB(Clob src, StringBuffer dest)
          reads the content of a CLOB into the specified StringBuffer
protected  FeatureMap readFeatures(Long entityID, int entityType)
          reads the features of an entity entities are of type LR or Annotation
 void setAutoSaving(boolean autoSaving)
          Set method for the autosaving behaviour of the data store.
 void setSecurityInfo(LanguageResource lr, SecurityInfo si)
          set security information for LR .
 void setStorageUrl(String storageUrl)
          Set the URL for the underlying storage mechanism.
 Long timestamp()
          Gets a timestamp marker that will be used for all changes made in the database so that subsequent calls to deleteSince() could restore (partly) the database state as it was before the update.
 void unlockLr(LanguageResource lr)
          Releases the exlusive lock on a resource from the persistent store.
protected  void updateDocumentContent(Long docID, DocumentContent content)
          updates the content of the document if it is binary or a long string (that does not fit into VARCHAR2)
static void writeBLOB(Object src, Blob dest)
          writes the specified object into the BLOB NOTE: the object should be serializable
static void writeCLOB(StringBuffer src, Clob dest)
          writes the content of a StringBuffer into the specified CLOB object
static void writeCLOB(String src, Clob dest)
          writes the content of a String into the specified CLOB object
 
Methods inherited from class gate.persist.JDBCDataStore
_adopt, _sync, _syncAddedAnnotations, _syncAnnotations, _syncAnnotationSets, _syncChangedAnnotations, _syncRemovedAnnotations, addDatastoreListener, adopt, beginTrans, canReadLR, canWriteLR, commitTrans, createCorpus, createDocument, createDocument, datastoreClosed, datastoreCreated, datastoreOpened, delete, delete, deleteSince, findFeatureType, fireResourceAdopted, fireResourceDeleted, fireResourceWritten, getComment, getDatabaseID, getIconName, getLockingUser, getLockingUser, getLr, getLrIds, getLrName, getLrNames, getLrTypes, getName, getSecurityInfo, getSession, readDatabaseID, removeDatastoreListener, resourceLoaded, resourceRenamed, resourceUnloaded, rollbackTrans, setName, setSession, sync, syncCorpus, syncDocument, unloadLR
 
Methods inherited from class gate.util.AbstractFeatureBearer
getFeatures, setFeatures
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface gate.util.FeatureBearer
getFeatures, setFeatures
 

Field Detail

DS_COMMENT

private static final String DS_COMMENT
Name of this resource

See Also:
Constant Field Values

DS_ICON_NAME

private static final String DS_ICON_NAME
the icon for this resource

See Also:
Constant Field Values

DEBUG

private static final boolean DEBUG
Debug flag

See Also:
Constant Field Values

ORACLE_TRUE

private static final int ORACLE_TRUE
"true" value for Oracle (supports no boolean type)

See Also:
Constant Field Values

ORACLE_FALSE

private static final int ORACLE_FALSE
"false" value for Oracle (supports no boolean type)

See Also:
Constant Field Values

VARRAY_SIZE

private static final int VARRAY_SIZE
size of the Oracle varrays used for bulc inserts

See Also:
Constant Field Values

ORACLE_VARCHAR_LIMIT_BYTES

private static final int ORACLE_VARCHAR_LIMIT_BYTES
the size in bytes if varchar2 column in Oracle when a String is stored in Oracle it may be too long for a varchar2 value, and then CLOB will be used Note that the limit is in bytes, not in characters, so in the worst case this will limit the string to 4000/3 characters

See Also:
Constant Field Values

UTF_BYTES_PER_CHAR_MAX

private static final int UTF_BYTES_PER_CHAR_MAX
maximum number of bytes that represent a char in UTF8 database

See Also:
Constant Field Values

ORACLE_VARCHAR_MAX_SYMBOLS

private static final int ORACLE_VARCHAR_MAX_SYMBOLS
maximum number of characters per string stored as varchar2 if longer then stored as CLOB

See Also:
Constant Field Values

INTERNAL_BUFFER_SIZE

private static final int INTERNAL_BUFFER_SIZE
read buffer size (for reading CLOBs)

See Also:
Constant Field Values
Constructor Detail

OracleDataStore

public OracleDataStore()
default constructor - just call the super constructor (may change in the future)

Method Detail

setStorageUrl

public void setStorageUrl(String storageUrl)
                   throws PersistenceException
Set the URL for the underlying storage mechanism.

Specified by:
setStorageUrl in interface DataStore
Overrides:
setStorageUrl in class JDBCDataStore
PersistenceException

getStorageUrl

public String getStorageUrl()
Get the URL for the underlying storage mechanism.

Specified by:
getStorageUrl in interface DataStore
Overrides:
getStorageUrl in class JDBCDataStore

create

public void create()
            throws PersistenceException,
                   UnsupportedOperationException
Create a new data store. NOTE: for some data stores creation is an system administrator task; in such cases this method will throw an UnsupportedOperationException.

Specified by:
create in interface DataStore
Overrides:
create in class JDBCDataStore
PersistenceException
UnsupportedOperationException

open

public void open()
          throws PersistenceException
Open a connection to the data store.

Specified by:
open in interface DataStore
Overrides:
open in class JDBCDataStore
PersistenceException

close

public void close()
           throws PersistenceException
Close the data store.

Specified by:
close in interface DataStore
Overrides:
close in class JDBCDataStore
PersistenceException

deleteDocument

protected void deleteDocument(Long lrId)
                       throws PersistenceException
helper method for delete() never call it directly beause proper events will not be fired

Specified by:
deleteDocument in class JDBCDataStore
PersistenceException

deleteCorpus

protected void deleteCorpus(Long lrId)
                     throws PersistenceException
helper method for delete() never call it directly beause proper events will not be fired

Specified by:
deleteCorpus in class JDBCDataStore
PersistenceException

setAutoSaving

public void setAutoSaving(boolean autoSaving)
                   throws UnsupportedOperationException,
                          PersistenceException
Set method for the autosaving behaviour of the data store. NOTE: many types of datastore have no auto-save function, in which case this will throw an UnsupportedOperationException.

Specified by:
setAutoSaving in interface DataStore
Overrides:
setAutoSaving in class JDBCDataStore
UnsupportedOperationException
PersistenceException

isAutoSaving

public boolean isAutoSaving()
Get the autosaving behaviour of the LR.

Specified by:
isAutoSaving in interface DataStore
Overrides:
isAutoSaving in class JDBCDataStore

createLR

protected Long createLR(String lrType,
                        String lrName,
                        SecurityInfo si,
                        Long lrParentID)
                 throws PersistenceException,
                        SecurityException
helper for adopt() never call directly

Specified by:
createLR in class JDBCDataStore
PersistenceException
SecurityException

updateDocumentContent

protected void updateDocumentContent(Long docID,
                                     DocumentContent content)
                              throws PersistenceException
updates the content of the document if it is binary or a long string (that does not fit into VARCHAR2)

Specified by:
updateDocumentContent in class JDBCDataStore
PersistenceException

createDoc

protected Long createDoc(Long _lrID,
                         URL _docURL,
                         String _docEncoding,
                         Long _docStartOffset,
                         Long _docEndOffset,
                         Boolean _docIsMarkupAware,
                         Long _corpusID)
                  throws PersistenceException
helper for adopt never call directly

Specified by:
createDoc in class JDBCDataStore
PersistenceException

createAnnotationSet

protected void createAnnotationSet(Long lrID,
                                   AnnotationSet aset)
                            throws PersistenceException
creates an entry for annotation set in the database

Specified by:
createAnnotationSet in class JDBCDataStore
PersistenceException

timestamp

public Long timestamp()
               throws PersistenceException
Gets a timestamp marker that will be used for all changes made in the database so that subsequent calls to deleteSince() could restore (partly) the database state as it was before the update. NOTE: Restoring the previous state may not be possible at all (i.e. if DELETE is performed)

Specified by:
timestamp in interface DatabaseDataStore
Overrides:
timestamp in class JDBCDataStore
PersistenceException

canAccessLR

protected boolean canAccessLR(Long lrID,
                              int mode)
                       throws PersistenceException,
                              SecurityException
Checks if the user (identified by the sessionID) has some access (read/write) to the LR

Overrides:
canAccessLR in class JDBCDataStore
PersistenceException
SecurityException

readCLOB

public static void readCLOB(Clob src,
                            StringBuffer dest)
                     throws SQLException,
                            IOException
reads the content of a CLOB into the specified StringBuffer

SQLException
IOException

writeCLOB

public static void writeCLOB(String src,
                             Clob dest)
                      throws SQLException,
                             IOException
writes the content of a String into the specified CLOB object

SQLException
IOException

writeCLOB

public static void writeCLOB(StringBuffer src,
                             Clob dest)
                      throws SQLException,
                             IOException
writes the content of a StringBuffer into the specified CLOB object

SQLException
IOException

readBLOB

public static Object readBLOB(Blob src)
                       throws SQLException,
                              IOException,
                              ClassNotFoundException
reads the content of the specified BLOB object and returns the object contained. NOTE: the BLOB is expected to contain serializable objects, not just any binary stream

SQLException
IOException
ClassNotFoundException

writeBLOB

public static void writeBLOB(Object src,
                             Blob dest)
                      throws SQLException,
                             IOException
writes the specified object into the BLOB NOTE: the object should be serializable

SQLException
IOException

_createFeature

private Long _createFeature(Long entityID,
                            int entityType,
                            String key,
                            Object value,
                            int valueType,
                            CallableStatement stmt)
                     throws PersistenceException
creates a feature of the specified type/value/valueType/key for the specified entity Entity is one of: LR, Annotation Value types are: boolean, int, long, string, float, Object

PersistenceException

_createFeatureBulk

private void _createFeatureBulk(Vector features,
                                CallableStatement stmt,
                                oracle.sql.ArrayDescriptor adNumber,
                                oracle.sql.ArrayDescriptor adString)
                         throws PersistenceException
creates a feature of the specified type/value/valueType/key for the specified entity Entity is one of: LR, Annotation Value types are: boolean, int, long, string, float, Object

PersistenceException

_updateFeatureLOB

private void _updateFeatureLOB(Long featID,
                               Object value,
                               int valueType)
                        throws PersistenceException
updates the value of a feature where the value is string (>4000 bytes, stored as CLOB) or Object (stored as BLOB)

PersistenceException

createFeature

private void createFeature(Long entityID,
                           int entityType,
                           String key,
                           Object value,
                           CallableStatement stmt)
                    throws PersistenceException
creates a feature with the specified type/key/value for the specified entity entitties are either LRs ot Annotations valid values are: boolean, int, long, string, float, Object, boolean List, int List, long List, string List, float List, Object List

PersistenceException

normalizeFeature

private Vector normalizeFeature(Long entityID,
                                int entityType,
                                String key,
                                Object value)
                         throws PersistenceException
splits complex features (Lists) into a vector of Feature entries each entry contains the entity id, entity type, feature key feature value value type

PersistenceException

fitsInVarchar2

private boolean fitsInVarchar2(String s)
checks if a String should be stores as VARCHAR2 or CLOB because the VARCHAR2 in Oracle is limited to 4000 bytes, not all the strings fit there. If a String is too long then it is store in the database as CLOB. Note that in the worst case 3 bytes are needed to represent a single character in a database with UTF8 encoding, which limits the string length to 4000/3 (ORACLE_VARCHAR_LIMIT_BYTES)

See Also:
ORACLE_VARCHAR_LIMIT_BYTES

createFeatures

protected void createFeatures(Long entityID,
                              int entityType,
                              FeatureMap features)
                       throws PersistenceException
helper metod iterates a FeatureMap and creates all its features in the database

Specified by:
createFeatures in class JDBCDataStore
PersistenceException

createFeaturesBulk

protected void createFeaturesBulk(Long entityID,
                                  int entityType,
                                  FeatureMap features)
                           throws PersistenceException
helper metod iterates a FeatureMap and creates all its features in the database since it uses Oracle VARRAYs the roundtrips between the client and the server are minimized make sure the two types STRING_ARRAY and INT_ARRAY have the same name in the PL/SQL files also when referencing the types always use the schema owner in upper case because the jdbc driver is buggy (see MetaLink note if u care)

Specified by:
createFeaturesBulk in class JDBCDataStore
PersistenceException

setSecurityInfo

public void setSecurityInfo(LanguageResource lr,
                            SecurityInfo si)
                     throws PersistenceException,
                            SecurityException
set security information for LR .

PersistenceException
SecurityException

readFeatures

protected FeatureMap readFeatures(Long entityID,
                                  int entityType)
                           throws PersistenceException
reads the features of an entity entities are of type LR or Annotation

Specified by:
readFeatures in class JDBCDataStore
PersistenceException

equals

public boolean equals(Object obj)
checks if two databases are identical

Overrides:
equals in class Object
See Also:
NOTE: the same database may be represented by different OracleDataStore instances but the IDs will be the same

_syncLR

protected void _syncLR(LanguageResource lr)
                throws PersistenceException,
                       SecurityException
helper for sync() NEVER call directly

Specified by:
_syncLR in class JDBCDataStore
PersistenceException
SecurityException

_syncDocumentHeader

protected void _syncDocumentHeader(Document doc)
                            throws PersistenceException
helper for sync() - never call directly

Specified by:
_syncDocumentHeader in class JDBCDataStore
PersistenceException

_syncDocumentContent

protected void _syncDocumentContent(Document doc)
                             throws PersistenceException
helper for sync() - never call directly

Specified by:
_syncDocumentContent in class JDBCDataStore
PersistenceException

_syncRemovedDocumentsFromCorpus

protected void _syncRemovedDocumentsFromCorpus(List docLRIDs,
                                               Long corpLRID)
                                        throws PersistenceException
helper for sync() - never call directly

Specified by:
_syncRemovedDocumentsFromCorpus in class JDBCDataStore
PersistenceException

_syncFeatures

protected void _syncFeatures(LanguageResource lr)
                      throws PersistenceException
helper for sync() - never call directly

Specified by:
_syncFeatures in class JDBCDataStore
PersistenceException

lockLr

public boolean lockLr(LanguageResource lr)
               throws PersistenceException,
                      SecurityException
Try to acquire exlusive lock on a resource from the persistent store. Always call unlockLR() when the lock is no longer needed

PersistenceException
SecurityException

_lockLr

private boolean _lockLr(Long lrID)
                 throws PersistenceException,
                        SecurityException
helper for lockLR() never call directly

PersistenceException
SecurityException

unlockLr

public void unlockLr(LanguageResource lr)
              throws PersistenceException,
                     SecurityException
Releases the exlusive lock on a resource from the persistent store.

PersistenceException
SecurityException

addDocumentToCorpus

protected void addDocumentToCorpus(Long docID,
                                   Long corpID)
                            throws PersistenceException,
                                   SecurityException
adds document to corpus in the database if the document is already part of the corpus nothing changes

Specified by:
addDocumentToCorpus in class JDBCDataStore
PersistenceException
SecurityException

findLrIds

public List findLrIds(List constraints)
               throws PersistenceException
Get a list of LRs that satisfy some set or restrictions

Specified by:
findLrIds in interface DataStore
Specified by:
findLrIds in class JDBCDataStore
Parameters:
constraints - list of Restriction objects
PersistenceException

findLrIds

public List findLrIds(List constraints,
                      String lrType)
               throws PersistenceException
Get a list of LRs IDs that satisfy some set or restrictions and are of a particular type

Specified by:
findLrIds in interface DataStore
Specified by:
findLrIds in class JDBCDataStore
Parameters:
constraints - list of Restriction objects
lrType - type of Lrs. DBHelper.DOCUMENT_CLASS or DBHelper.CORPUS_CLASS
PersistenceException

findLrIds

public List findLrIds(List constraints,
                      String lrType,
                      List orderByConstraints,
                      int limitcount)
               throws PersistenceException
Get a list of LRs IDs that satisfy some set or restrictions and are of a particular type

Parameters:
constraints - list of Restriction objects
lrType - type of Lrs. DBHelper.DOCUMENT_CLASS or DBHelper.CORPUS_CLASS
orderByConstraints - liat of OrderByRestriction objects
limitcount - limit returning objects -1 for unlimited
PersistenceException

getLrsCount

public long getLrsCount(List constraints,
                        String lrType)
                 throws PersistenceException
Return count of LRs which matches the constraints.

Parameters:
constraints - list of Restriction objects
lrType - type of Lrs. DBHelper.DOCUMENT_CLASS or DBHelper.CORPUS_CLASS
PersistenceException

getSQLQuery

private String getSQLQuery(List filter,
                           String lrType,
                           boolean count,
                           List orderByFilter,
                           int limitcount,
                           Vector sqlValues)

getIntersectionPart

private String getIntersectionPart(List filter,
                                   Vector sqlValues)

getRestrictionPartOfQuery

private String getRestrictionPartOfQuery(List list,
                                         Vector sqlValues)

getNumberExpresion

private String getNumberExpresion(Restriction restr,
                                  Vector sqlValues)

getJoinQuery

private String getJoinQuery(List orderByFilter,
                            Vector sqlValues)

getEndPartOfJoin

private String getEndPartOfJoin(List orderByFilter,
                                String lrType,
                                Vector sqlValues)

findDocIdsByAnn

public List findDocIdsByAnn(List constraints,
                            int limitcount)
                     throws PersistenceException
PersistenceException

getSQLQueryAnn

private String getSQLQueryAnn(List constraints,
                              int limitcount,
                              Vector sqlValues)