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

Field Summary
private static boolean DEBUG
          Debug flag
static String DS_COMMENT
          Name of this resource
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 READ_ACCESS
          used internaly, may change in the future
private static int UTF_BYTES_PER_CHAR_MAX
          maximum number of bytes that represent a char in UTF8 database
private static int WRITE_ACCESS
          used internaly, may change in the future
 
Fields inherited from class gate.persist.JDBCDataStore
ac, datastoreListeners, dbID, dbURL, dependentResources, driverName, jdbcConn, name, session
 
Fields inherited from class gate.util.AbstractFeatureBearer
features, serialVersionUID
 
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  LanguageResource _adopt(LanguageResource lr, SecurityInfo secInfo, boolean openNewTrans)
          helper for adopt()
private  Long _createFeature(Long entityID, int entityType, String key, Object value, int valueType)
          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
private  void _sync(LanguageResource lr, boolean openNewTrans)
          Save: synchonise the in-memory image of the LR with the persistent image.
private  void _syncAddedAnnotations(Document doc, AnnotationSet as, Collection changes)
          helper for sync() - never call directly
private  void _syncAnnotations(Document doc)
          helper for sync() - never call directly
private  void _syncAnnotationSets(Document doc, Collection removedSets, Collection addedSets)
          helper for sync() - never call directly
private  void _syncChangedAnnotations(Document doc, AnnotationSet as, Collection changes)
          helper for sync() - never call directly
private  void _syncDocument(Document doc)
          helper for sync() - never call directly
private  void _syncDocumentContent(Document doc)
          helper for sync() - never call directly
private  void _syncFeatures(LanguageResource lr)
          helper for sync() - never call directly
private  void _syncLR(Long lrID, String newName)
          helper for sync() NEVER call directly
private  void _syncRemovedAnnotations(Document doc, AnnotationSet as, Collection changes)
          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)
private  void addDocumentToCorpus(Long docID, Long corpID)
          adds document to corpus in the database if the document is already part of the corpus nothing changes
 LanguageResource adopt(LanguageResource lr, SecurityInfo secInfo)
          Adopt a resource for persistence.
private  boolean canAccessLR(Long lrID, int mode)
          Checks if the user (identified by the sessionID) has some access (read/write) to the LR
 boolean canReadLR(Object lrID)
          Checks if the user (identified by the sessionID) has read access to the LR
 boolean canWriteLR(Object lrID)
          Checks if the user (identified by the sessionID) has write access to the LR
 void close()
          Close the data store.
 void create()
          Create a new data store.
private  void createAnnotationSet(Long lrID, AnnotationSet aset)
          creates an entry for annotation set in the database
private  Corpus createCorpus(Corpus corp, SecurityInfo secInfo)
          creates a LR of type Corpus
private  Document createDocument(Document doc, Long corpusID, SecurityInfo secInfo)
          helper for adopt creates a LR of type Document
private  Document createDocument(Document doc, SecurityInfo secInfo)
          helper for adopt creates a LR of type Document
private  void createFeature(Long entityID, int entityType, String key, Object value)
          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
private  void createFeatures(Long entityID, int entityType, FeatureMap features)
          helper metod iterates a FeatureMap and creates all its features in the database
private  Long createLR(String lrType, String lrName, SecurityInfo si, Long lrParentID)
          helper for adopt() never call directly
 void delete()
          Delete the data store.
 void delete(String lrClassName, Object lrId)
          Delete a resource from the data store.
private  void deleteCorpus(Long lrId)
          helper method for delete() never call it directly beause proper events will not be fired
private  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
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.
 String getComment()
          Save: synchonise the in-memory image of the LR with the persistent image.
 String getIconName()
          Returns the name of the icon to be used when this datastore is displayed in the GUI
private  User getLockingUser(LanguageResource lr)
          Releases the exlusive lock on a resource from the persistent store.
private  User getLockingUser(Long lrID)
          Releases the exlusive lock on a resource from the persistent store.
 LanguageResource getLr(String lrClassName, Object lrPersistenceId)
          Get a resource from the persistent store.
 List getLrIds(String lrType)
          Get a list of the IDs of LRs of a particular type that are present.
 String getLrName(Object lrId)
          Get the name of an LR from its ID.
 List getLrNames(String lrType)
          Get a list of the names of LRs of a particular type that are present.
 List getLrTypes()
          Get a list of the types of LR that are present in the data store.
 SecurityInfo getSecurityInfo(LanguageResource lr)
          get security information for LR .
 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.
 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
private  DatabaseCorpusImpl readCorpus(Object lrPersistenceId)
          helper method for getLR - reads LR of type Corpus
 String readDatabaseID()
          reads the ID of the database every database should have unique string ID
private  DatabaseDocumentImpl readDocument(Object lrPersistenceId)
          helper method for getLR - reads LR of type Document
private  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.
 void sync(LanguageResource lr)
          Save: synchonise the in-memory image of the LR with the persistent image.
private  void syncCorpus(Corpus corp)
          helper for sync() - saves a Corpus in the database
private  void syncDocument(Document doc)
          helper for sync() - saves a Document in the database
 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.
private  void unloadLR(Long lrID)
          unloads a LR from the GUI
 void unlockLr(LanguageResource lr)
          Releases the exlusive lock on a resource from the persistent store.
private  void updateDocumentContent(Long docContentID, 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
addDatastoreListener, beginTrans, commitTrans, datastoreClosed, datastoreCreated, datastoreOpened, deleteSince, findFeatureType, fireResourceAdopted, fireResourceDeleted, fireResourceWritten, getDatabaseID, getName, getSession, removeDatastoreListener, resourceLoaded, resourceUnloaded, rollbackTrans, setDriver, setName, setSession
 
Methods inherited from class gate.util.AbstractFeatureBearer
getFeatures, setFeatures
 
Methods inherited from class java.lang.Object
, clone, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 
Methods inherited from interface gate.util.FeatureBearer
getFeatures, setFeatures
 

Field Detail

DS_COMMENT

public static final String DS_COMMENT
Name of this resource

DS_ICON_NAME

public static final String DS_ICON_NAME
the icon for this resource

DEBUG

private static final boolean DEBUG
Debug flag

ORACLE_TRUE

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

ORACLE_FALSE

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

READ_ACCESS

private static final int READ_ACCESS
used internaly, may change in the future

WRITE_ACCESS

private static final int WRITE_ACCESS
used internaly, may change in the future

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

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

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

INTERNAL_BUFFER_SIZE

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

OracleDataStore

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

getComment

public String getComment()
Save: synchonise the in-memory image of the LR with the persistent image.
Overrides:
getComment in class JDBCDataStore

getIconName

public String getIconName()
Returns the name of the icon to be used when this datastore is displayed in the GUI
Overrides:
getIconName in class JDBCDataStore

getLrName

public String getLrName(Object lrId)
                 throws PersistenceException
Get the name of an LR from its ID.
Overrides:
getLrName in class JDBCDataStore

setStorageUrl

public void setStorageUrl(String storageUrl)
                   throws PersistenceException
Set the URL for the underlying storage mechanism.
Overrides:
setStorageUrl in class JDBCDataStore

getStorageUrl

public String getStorageUrl()
Get the URL for the underlying storage mechanism.
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.
Overrides:
create in class JDBCDataStore

open

public void open()
          throws PersistenceException
Open a connection to the data store.
Overrides:
open in class JDBCDataStore

close

public void close()
           throws PersistenceException
Close the data store.
Overrides:
close in class JDBCDataStore

delete

public void delete()
            throws PersistenceException,
                   UnsupportedOperationException
Delete the data store. NOTE: for some data stores deletion is an system administrator task; in such cases this method will throw an UnsupportedOperationException.
Overrides:
delete in class JDBCDataStore

delete

public void delete(String lrClassName,
                   Object lrId)
            throws PersistenceException,
                   SecurityException
Delete a resource from the data store.
Overrides:
delete in class JDBCDataStore
Parameters:
lrId - a data-store specific unique identifier for the resource
lrClassName - class name of the type of resource

deleteDocument

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

deleteCorpus

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

sync

public void sync(LanguageResource lr)
          throws PersistenceException,
                 SecurityException
Save: synchonise the in-memory image of the LR with the persistent image.
Overrides:
sync in class JDBCDataStore

_sync

private void _sync(LanguageResource lr,
                   boolean openNewTrans)
            throws PersistenceException,
                   SecurityException
Save: synchonise the in-memory image of the LR with the persistent image.

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.
Overrides:
setAutoSaving in class JDBCDataStore

isAutoSaving

public boolean isAutoSaving()
Get the autosaving behaviour of the LR.
Overrides:
isAutoSaving in class JDBCDataStore

adopt

public LanguageResource adopt(LanguageResource lr,
                              SecurityInfo secInfo)
                       throws PersistenceException,
                              SecurityException
Adopt a resource for persistence.
Overrides:
adopt in class JDBCDataStore

_adopt

private LanguageResource _adopt(LanguageResource lr,
                                SecurityInfo secInfo,
                                boolean openNewTrans)
                         throws PersistenceException,
                                SecurityException
helper for adopt()
Parameters:
openNewTrans - shows if a new transaction should be started or the adopt is performed in the context of an already opened transaction

createLR

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

updateDocumentContent

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

createDocument

private Document createDocument(Document doc,
                                SecurityInfo secInfo)
                         throws PersistenceException,
                                SecurityException
helper for adopt creates a LR of type Document

createDocument

private Document createDocument(Document doc,
                                Long corpusID,
                                SecurityInfo secInfo)
                         throws PersistenceException,
                                SecurityException
helper for adopt creates a LR of type Document

createAnnotationSet

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

createCorpus

private Corpus createCorpus(Corpus corp,
                            SecurityInfo secInfo)
                     throws PersistenceException,
                            SecurityException
creates a LR of type Corpus

getLr

public LanguageResource getLr(String lrClassName,
                              Object lrPersistenceId)
                       throws PersistenceException,
                              SecurityException
Get a resource from the persistent store. Don't use this method - use Factory.createResource with DataStore and DataStoreInstanceId parameters set instead.
Overrides:
getLr in class JDBCDataStore

getLrTypes

public List getLrTypes()
                throws PersistenceException
Get a list of the types of LR that are present in the data store.
Overrides:
getLrTypes in class JDBCDataStore

getLrIds

public List getLrIds(String lrType)
              throws PersistenceException
Get a list of the IDs of LRs of a particular type that are present.
Overrides:
getLrIds in class JDBCDataStore

getLrNames

public List getLrNames(String lrType)
                throws PersistenceException
Get a list of the names of LRs of a particular type that are present.
Overrides:
getLrNames in class JDBCDataStore

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)
Overrides:
timestamp in class JDBCDataStore

canReadLR

public boolean canReadLR(Object lrID)
                  throws PersistenceException,
                         SecurityException
Checks if the user (identified by the sessionID) has read access to the LR
Overrides:
canReadLR in class JDBCDataStore

canWriteLR

public boolean canWriteLR(Object lrID)
                   throws PersistenceException,
                          SecurityException
Checks if the user (identified by the sessionID) has write access to the LR
Overrides:
canWriteLR in class JDBCDataStore

canAccessLR

private 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

readCLOB

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

writeCLOB

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

writeCLOB

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

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

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

_createFeature

private Long _createFeature(Long entityID,
                            int entityType,
                            String key,
                            Object value,
                            int valueType)
                     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

_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)

createFeature

private void createFeature(Long entityID,
                           int entityType,
                           String key,
                           Object value)
                    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

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

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

getSecurityInfo

public SecurityInfo getSecurityInfo(LanguageResource lr)
                             throws PersistenceException
get security information for LR .

setSecurityInfo

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

readCorpus

private DatabaseCorpusImpl readCorpus(Object lrPersistenceId)
                               throws PersistenceException
helper method for getLR - reads LR of type Corpus

readDocument

private DatabaseDocumentImpl readDocument(Object lrPersistenceId)
                                   throws PersistenceException
helper method for getLR - reads LR of type Document

readFeatures

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

readDatabaseID

public String readDatabaseID()
                      throws PersistenceException
reads the ID of the database every database should have unique string ID
Overrides:
readDatabaseID in class JDBCDataStore

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

syncDocument

private void syncDocument(Document doc)
                   throws PersistenceException
helper for sync() - saves a Document in the database

_syncLR

private void _syncLR(Long lrID,
                     String newName)
              throws PersistenceException
helper for sync() NEVER call directly

_syncDocument

private void _syncDocument(Document doc)
                    throws PersistenceException
helper for sync() - never call directly

_syncDocumentContent

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

_syncAddedAnnotations

private void _syncAddedAnnotations(Document doc,
                                   AnnotationSet as,
                                   Collection changes)
                            throws PersistenceException
helper for sync() - never call directly

_syncChangedAnnotations

private void _syncChangedAnnotations(Document doc,
                                     AnnotationSet as,
                                     Collection changes)
                              throws PersistenceException
helper for sync() - never call directly

_syncRemovedAnnotations

private void _syncRemovedAnnotations(Document doc,
                                     AnnotationSet as,
                                     Collection changes)
                              throws PersistenceException
helper for sync() - never call directly

_syncAnnotationSets

private void _syncAnnotationSets(Document doc,
                                 Collection removedSets,
                                 Collection addedSets)
                          throws PersistenceException
helper for sync() - never call directly

_syncAnnotations

private void _syncAnnotations(Document doc)
                       throws PersistenceException
helper for sync() - never call directly

_syncFeatures

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

syncCorpus

private void syncCorpus(Corpus corp)
                 throws PersistenceException
helper for sync() - saves a Corpus in the database

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

_lockLr

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

unlockLr

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

getLockingUser

private User getLockingUser(LanguageResource lr)
                     throws PersistenceException,
                            SecurityException
Releases the exlusive lock on a resource from the persistent store.

getLockingUser

private User getLockingUser(Long lrID)
                     throws PersistenceException,
                            SecurityException
Releases the exlusive lock on a resource from the persistent store.

addDocumentToCorpus

private 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

unloadLR

private void unloadLR(Long lrID)
               throws GateException
unloads a LR from the GUI