com.pixelmed.database
Class DatabaseInformationModel

java.lang.Object
  com.pixelmed.database.DatabaseInformationModel

Direct Known Subclasses:

DicomDatabaseInformationModel

public abstract class DatabaseInformationModel
extends Object

The DatabaseInformationModel class is an abstract class that contains the core functionality for storing, accessing and maintaining a persistent representation of selected attributes of composite objects.

It hides an underlying SQL database implementation that stores the attributes of each entity in the information model in tables.

Abstract sub-classes, such as DicomDatabaseInformationModel, may refine the type of information model supported, since this base class is fairly generic and not dependent on any particular DICOM information model. Concrete sub-classes define particular models by overriding the methods that define the root entities and the relationship between entities, as well as the unique keys for each particular entity.

In addition, the concrete sub-classes define which attributes of each entity will be included in the persistent representation (the database tables), usually by means of a specialized sub-class of DicomDictionary which contains the sub-set of relevant attributes and may change their mapping to information entities, such as DicomDictionaryForPatientStudySeriesConcatenationInstanceModel.

For example, an application might instantiate a PatientStudySeriesConcatenationInstanceModel or a StudySeriesInstanceModel, as follows:

        final DatabaseInformationModel d = new PatientStudySeriesConcatenationInstanceModel("test");
 

Composite objects previously read into a AttributeList from a DICOM file in a persistent location could be inserted into the persistent representation (the database) as follows:

        d.insertObject(list,fileName);
 

External (unsecure) SQL access to the database is possible if a databaseServerName argument is supplied in the constructor, in which case a tool like org.hsqldb.util.DatabaseManagerSwing (described in detail at Hsqldb User Guide: Appendix F. Database Manager) can be used to query or manage the database. For example:

% java -cp lib/additional/hsqldb.jar org.hsqldb.util.DatabaseManagerSwing --url "jdbc:hsqldb:hsql://hostname/databaseServerName"
 

where "hostname" is the name of the host (perhaps "localhost"), and "databaseServerName" is the name supplied in the constructor.

Note that the default username ("sa") and password (empty) are not secure.

See Also:

com.pixelmed.database

Field Summary

protected HashMap	additionalIndexMapOfColumnsToTables
protected Connection	databaseConnection
protected String	databaseRootName
protected static String	defaultDatabaseRootName
protected DicomDictionary	dictionary
protected Server	externalServerInstance
protected HashMap	listsOfAttributesByInformationEntity
protected static String	localFileName
protected static String	localParentReferenceColumnName
protected static String	localPrimaryKeyColumnName
protected static String	localRecordInsertionTimeColumnName
protected static String	personNameCanonicalColumnNamePrefix
protected static String	personNameCanonicalColumnNameSuffix
protected static String	personNamePhoneticCanonicalColumnNamePrefix
protected static String	personNamePhoneticCanonicalColumnNameSuffix
protected InformationEntity	rootInformationEntity
protected static String	userColumnName1
protected static String	userColumnName2
protected static String	userColumnName3
protected static String	userColumnName4

Constructor Summary

DatabaseInformationModel(String databaseFileName, InformationEntity rootInformationEntity, DicomDictionary dictionary)
Instantiate a persistent information model using the named database.

DatabaseInformationModel(String databaseFileName, InformationEntity rootInformationEntity, DicomDictionary dictionary, String databaseRootName)
Instantiate a persistent information model using the named database.

DatabaseInformationModel(String databaseFileName, String databaseServerName, InformationEntity rootInformationEntity, DicomDictionary dictionary)
Instantiate a persistent information model using the named database allowing external SQL access.

DatabaseInformationModel(String databaseFileName, String databaseServerName, InformationEntity rootInformationEntity, DicomDictionary dictionary, String databaseRootName)
Instantiate a persistent information model using the named database allowing external SQL access.

Method Summary

protected static void	appendExactOrIsNullMatch(StringBuffer b, String value) Append a check for a match against a string value, accounting for the need to use the "IS NULL" rather than "=" expression when wanting to explciitly have NULL match NULL rather to never match.
void	close() Close the underlying connection to the database and shutdown any external SQL server.
protected void	createAdditionalIndexes() Create any additional indexes to optimize queries, for example for UIDs.
protected abstract String	createPrimaryKeyForSelectedInformationEntity(InformationEntity ie) Create a new unique key which may be used to identify a new instance of an entity.
void	deleteSelectedRecord(InformationEntity ie, String localPrimaryKeyValue) For a particular instance of an information entity, delete the record from the database table.
protected void	doCommonConstructorStuff(String databaseFileName, String databaseServerName, InformationEntity rootInformationEntity, DicomDictionary dictionary, String databaseRootName) Instantiate a persistent information model using the named database.
protected void	extendCreateStatementStringWithAnyExtraAttributes(StringBuffer b, InformationEntity ie) Extend a SQL CREATE TABLE statement in the process of being constructed with any additional attributes (columns) that the model requires.
protected void	extendCreateStatementStringWithDerivedAttributes(StringBuffer b, InformationEntity ie) Extend a SQL CREATE TABLE statement in the process of being constructed with any derived attributes (columns) that the model requires.
protected void	extendCreateStatementStringWithUserColumns(StringBuffer b, InformationEntity ie) Extend a SQL CREATE TABLE statement in the process of being constructed with any user optional columns that the model requires.
protected abstract void	extendInsertStatementStringWithAttributeNamesForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie) Extend a SQL INSERT statement in the process of being constructed with the names of the attributes in the instance for the entity.
protected abstract void	extendInsertStatementStringWithAttributeValuesForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie, String fileName) Extend a SQL INSERT statement in the process of being constructed with the values of the attributes in the instance for the entity.
protected abstract void	extendInsertStatementStringWithDerivedAttributeNamesForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie) Extend a SQL INSERT statement in the process of being constructed with the names of the derived attributes in the instance for the entity.
protected abstract void	extendInsertStatementStringWithDerivedAttributeValuesForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie) Extend a SQL INSERT statement in the process of being constructed with the values of the derived attributes in the instance for the entity.
protected abstract void	extendInsertStatementStringWithPersonNameSearchColumnsForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie) Extend a SQL INSERT statement in the process of being constructed with the names of the additional search columns derived from person name attributes in the instance for the entity.
protected abstract void	extendInsertStatementStringWithPersonNameSearchValuesForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie) Extend a SQL INSERT statement in the process of being constructed with the values of the additional search columns derived from person name attributes in the instance for the entity.
protected abstract void	extendStatementStringWithMatchingAttributesForSelectedInformationEntity(StringBuffer b, AttributeList list, InformationEntity ie) Extend a SQL SELECT statement in the process of being constructed with matching clauses for the unique keys of the entity and all its parents.
protected void	finalize()
ArrayList	findAllAttributeValuesForAllRecordsForThisInformationEntity(InformationEntity ie) For all records of an information entity, get the values of all the columns in the entity's database table.
ArrayList	findAllAttributeValuesForAllRecordsForThisInformationEntityWithMatchingParent(InformationEntity ieWanted, InformationEntity ieParent, String parentMatchingAttribute, String parentMatchingValue) For all records of an information entity with all parents matching a particular attribute value, get the values of all attributes.
ArrayList	findAllAttributeValuesForAllRecordsForThisInformationEntityWithSpecifiedParent(InformationEntity ie, String localParentReference) For all records of an information entity with the specified parent, get the values of all the columns in the entity's database table.
ArrayList	findAllAttributeValuesForAllRecordsForThisInformationEntityWithSpecifiedUID(InformationEntity ie, String uid) For all records of an information entity matching the specified UID, get the values of all the columns in the entity's database table.
Map	findAllAttributeValuesForSelectedRecord(InformationEntity ie, String localPrimaryKeyValue) For a particular instance of an information entity, get the values of all the columns in the entity's database table.
abstract InformationEntity	getChildTypeForParent(InformationEntity ie) For an information entity (regardless of a particular instance), find the next information entity lower down in the information model hierarchy in the general case.
abstract InformationEntity	getChildTypeForParent(InformationEntity ie, AttributeList list) For a particular instance of an information entity, find the next information entity lower down in the information model hierarchy.
abstract InformationEntity	getChildTypeForParent(InformationEntity ie, boolean concatenation) For a particular instance of an information entity, find the next information entity lower down in the information model hierarchy.
abstract String	getDescriptiveColumnName(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the first of three descriptive attributes for the entity.
InformationEntity	getInformationEntityFromTag(AttributeTag tag) Get the information entity in this information model for the specified tag
String	getLocalParentReferenceColumnName(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the reference to an instance of the entity's parent.
String	getLocalPrimaryKeyColumnName(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the primary key of an instance of the entity.
abstract String	getNametoDescribeThisInstanceOfInformationEntity(InformationEntity ie, Map returnedAttributes) For a particular instance of an information entity, find a descriptive name for the entity suitable for rendering.
abstract String	getOtherDescriptiveColumnName(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the second of three descriptive attributes for the entity.
abstract String	getOtherOtherDescriptiveColumnName(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the third of three descriptive attributes for the entity.
QueryResponseGeneratorFactory	getQueryResponseGeneratorFactory(int debugLevel) Get a factory to manufacture a query response generator capable of performing a query and returning the results.
RetrieveResponseGeneratorFactory	getRetrieveResponseGeneratorFactory(int debugLevel) Get a factory to manufacture a retrieve response generator capable of performing a retrieve and returning the results.
static String	getSQLTypeFromDicomValueRepresentation(byte[] vr) Given a DICOM Value Representation, determine the appropriate corresponding SQL type to use.
abstract String	getUIDColumnNameForInformationEntity(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the DICOM UID for the entity.
void	insertObject(AttributeList list, String fileName) Insert a DICOM composite object, and the relevant attributes of all the entities it contains, into the database.
protected abstract boolean	isInformationEntityInModel(InformationEntity ie) Is the entity in the information model ?
protected boolean	isInformationEntityInModel(String ieName) Is the named entity in the information model ?
String	localFileNameColumnName(InformationEntity ie) For a particular information entity, find the name of the column in the entity's database table containing the local file name of a stored object.
protected void	setDatabaseProperties()
String	toString() Returns a string describing the structure (not the contents) of the database.
void	updateSelectedRecord(InformationEntity ie, String localPrimaryKeyValue, String key, String value) For a particular instance of an information entity, update the record in the database table with a new value for the specified attribute (column).

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

defaultDatabaseRootName

protected static final String defaultDatabaseRootName

See Also:

Constant Field Values

localPrimaryKeyColumnName

protected static final String localPrimaryKeyColumnName

See Also:

Constant Field Values

localParentReferenceColumnName

protected static final String localParentReferenceColumnName

See Also:

Constant Field Values

localRecordInsertionTimeColumnName

protected static final String localRecordInsertionTimeColumnName

See Also:

Constant Field Values

localFileName

protected static final String localFileName

See Also:

Constant Field Values

personNameCanonicalColumnNamePrefix

protected static final String personNameCanonicalColumnNamePrefix

See Also:

Constant Field Values

personNameCanonicalColumnNameSuffix

protected static final String personNameCanonicalColumnNameSuffix

See Also:

Constant Field Values

personNamePhoneticCanonicalColumnNamePrefix

protected static final String personNamePhoneticCanonicalColumnNamePrefix

See Also:

Constant Field Values

personNamePhoneticCanonicalColumnNameSuffix

protected static final String personNamePhoneticCanonicalColumnNameSuffix

See Also:

Constant Field Values

userColumnName1

protected static final String userColumnName1

See Also:

Constant Field Values

userColumnName2

protected static final String userColumnName2

See Also:

Constant Field Values

userColumnName3

protected static final String userColumnName3

See Also:

Constant Field Values

userColumnName4

protected static final String userColumnName4

See Also:

Constant Field Values

rootInformationEntity

protected InformationEntity rootInformationEntity

listsOfAttributesByInformationEntity

protected HashMap listsOfAttributesByInformationEntity

additionalIndexMapOfColumnsToTables

protected HashMap additionalIndexMapOfColumnsToTables

databaseConnection

protected Connection databaseConnection

externalServerInstance

protected Server externalServerInstance

dictionary

protected DicomDictionary dictionary

databaseRootName

protected String databaseRootName

Constructor Detail

DatabaseInformationModel

public DatabaseInformationModel(String databaseFileName,
                                InformationEntity rootInformationEntity,
                                DicomDictionary dictionary)
                         throws DicomException

Instantiate a persistent information model using the named database.

Will open a connection to the database, and create any tables if this is the first time, or re-use any persistent information if not.

Parameters:

databaseFileName - the file name of the underlying SQL database instance to be used

rootInformationEntity - the top entity of the information model; specific to a particular model's constructor

dictionary - used to decide which attributes to include for each entity when creating the tables

Throws:

DicomException - thrown if a connection to the database cannot be established

DatabaseInformationModel

public DatabaseInformationModel(String databaseFileName,
                                InformationEntity rootInformationEntity,
                                DicomDictionary dictionary,
                                String databaseRootName)
                         throws DicomException

Instantiate a persistent information model using the named database.

Will open a connection to the database, and create any tables if this is the first time, or re-use any persistent information if not.

Parameters:

databaseFileName - the file name of the underlying SQL database instance to be used

rootInformationEntity - the top entity of the information model; specific to a particular model's constructor

dictionary - used to decide which attributes to include for each entity when creating the tables

databaseRootName - the name used for the root node of the database in TreeModel

Throws:

DicomException - thrown if a connection to the database cannot be established

DatabaseInformationModel

public DatabaseInformationModel(String databaseFileName,
                                String databaseServerName,
                                InformationEntity rootInformationEntity,
                                DicomDictionary dictionary)
                         throws DicomException

Instantiate a persistent information model using the named database allowing external SQL access.

Will open a connection to the database, and create any tables if this is the first time, or re-use any persistent information if not.

Parameters:

databaseFileName - the file name of the underlying SQL database instance to be used

databaseServerName - the name to use for external TCP access to database (such a server will not be started if this value is null or zero length)

rootInformationEntity - the top entity of the information model; specific to a particular model's constructor

dictionary - used to decide which attributes to include for each entity when creating the tables

Throws:

DicomException - thrown if a connection to the database cannot be established

DatabaseInformationModel

public DatabaseInformationModel(String databaseFileName,
                                String databaseServerName,
                                InformationEntity rootInformationEntity,
                                DicomDictionary dictionary,
                                String databaseRootName)
                         throws DicomException

Instantiate a persistent information model using the named database allowing external SQL access.

Will open a connection to the database, and create any tables if this is the first time, or re-use any persistent information if not.

Parameters:

databaseFileName - the file name of the underlying SQL database instance to be used

databaseServerName - the name to use for external TCP access to database (such a server will not be started if this value is null or zero length)

rootInformationEntity - the top entity of the information model; specific to a particular model's constructor

dictionary - used to decide which attributes to include for each entity when creating the tables

databaseRootName - the name used for the root node of the database in TreeModel

Throws:

DicomException - thrown if a connection to the database cannot be established

Method Detail

setDatabaseProperties

protected void setDatabaseProperties()

doCommonConstructorStuff

protected void doCommonConstructorStuff(String databaseFileName,
                                        String databaseServerName,
                                        InformationEntity rootInformationEntity,
                                        DicomDictionary dictionary,
                                        String databaseRootName)
                                 throws DicomException

Instantiate a persistent information model using the named database.

Will open a connection to the database, and create any tables if this is the first time, or re-use any persistent information if not.

Parameters:

databaseFileName - the file name of the underlying SQL database instance to be used (or "mem:name" if the database is to be in-memory and not persisted)

databaseServerName - the name to use for external TCP access to database (such a server will not be started if this value is null or zero length)

rootInformationEntity - the top entity of the information model; specific to a particular model's constructor

dictionary - used to decide which attributes to include for each entity when creating the tables

databaseRootName - the name used for the root node of the database in TreeModel

Throws:

DicomException - thrown if a connection to the database cannot be established

close

public void close()

Close the underlying connection to the database and shutdown any external SQL server.

Prior to actually closing will also try to formally shutdown and compact the database.

finalize

protected void finalize()

Overrides:

finalize in class Object

isInformationEntityInModel

protected abstract boolean isInformationEntityInModel(InformationEntity ie)

Is the entity in the information model ?

Will be specific to a particular concrete information model.

Returns:

boolean the information entity is in the information model

isInformationEntityInModel

protected boolean isInformationEntityInModel(String ieName)

Is the named entity in the information model ?

Will be specific to a particular concrete information model.

Parameters:

ieName - a String name, whose case is ignored (e.g., a database table named for the corresponding information entity)

Returns:

the name corresponds to an information entity that is in the information model

createAdditionalIndexes

protected void createAdditionalIndexes()
                                throws DicomException

Create any additional indexes to optimize queries, for example for UIDs.

Called after creating tables and default indexes.

Throws:

DicomException

extendCreateStatementStringWithAnyExtraAttributes

protected void extendCreateStatementStringWithAnyExtraAttributes(StringBuffer b,
                                                                 InformationEntity ie)

Extend a SQL CREATE TABLE statement in the process of being constructed with any additional attributes (columns) that the model requires.

Called when creating the tables for a new database.

Specific to each concrete information model extending DatabaseInformationModel. Defaults to adding no extra columns if not overridden (i.e. it is not abstract).

For example, there may be a DICOM attribute that is defined to be in a particular information entity in the dictionary (for example InstanceNumber is at the concatenation level), but for the convenience of the user of tree and table browsers it may be nice to replicate it into the tables for lower levels of the information model as well; hence this method might add InstanceNumber at the instance level. Once created, such attributes will automatically be included during database inserts. See also PatientStudySeriesConcatenationInstanceModel for example.

Parameters:

b - the statement being constructed

ie - the InformationEntity for which a create table statement is being constructed

extendCreateStatementStringWithDerivedAttributes

protected void extendCreateStatementStringWithDerivedAttributes(StringBuffer b,
                                                                InformationEntity ie)

Extend a SQL CREATE TABLE statement in the process of being constructed with any derived attributes (columns) that the model requires.

Called when creating the tables for a new database.

Specific to each concrete information model extending DatabaseInformationModel. Defaults to adding no extra columns if not overridden (i.e. it is not abstract).

For example, there may be dates and times derived from DICOM attributes.

Parameters:

b - the statement being constructed

ie - the InformationEntity for which a create table statement is being constructed

extendCreateStatementStringWithUserColumns

protected void extendCreateStatementStringWithUserColumns(StringBuffer b,
                                                          InformationEntity ie)

Extend a SQL CREATE TABLE statement in the process of being constructed with any user optional columns that the model requires.

Called when creating the tables for a new database.

Specific to each concrete information model extending DatabaseInformationModel. Defaults to adding four extra columns for each table if not overridden (i.e. it is not abstract).

Parameters:

b - the statement being constructed

ie - the InformationEntity for which a create table statement is being constructed

insertObject

public void insertObject(AttributeList list,
                         String fileName)
                  throws DicomException

Insert a DICOM composite object, and the relevant attributes of all the entities it contains, into the database.

Such a composite object may contain information about the patient, study, series and instance and so on, and for each of these entities the appropriate records will be created in the appropriate tables

If records for any entities already exist (as they will often do when inserting multiple objects for the same patient or study, for example), they are matched based on the unique key for the appropriate level. They are not replaced and they are not updated, even if some of the attributes for that entity (other than the unique key) are different or additional. Even at the instance level (e.g. if an object with the same SOPInstanceUID is received), the first record will not be overwritten. Whether or not the application calling this method will have overwritten the corresponding file in the supplied argument or not is outside the scope of this class.

The information is taken from the supplied AttributeList, which is presumed to have already been read from a file or obtained through some other means. The supplied filename is only used to fill in the appropriate instance level attribute.

Parameters:

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

fileName - the name of a file where the object is stored and from whence it may later be read

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendInsertStatementStringWithPersonNameSearchColumnsForSelectedInformationEntity

protected abstract void extendInsertStatementStringWithPersonNameSearchColumnsForSelectedInformationEntity(StringBuffer b,
                                                                                                           AttributeList list,
                                                                                                           InformationEntity ie)
                                                                                                    throws DicomException

Extend a SQL INSERT statement in the process of being constructed with the names of the additional search columns derived from person name attributes in the instance for the entity.

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which a select statement is being constructed

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendInsertStatementStringWithPersonNameSearchValuesForSelectedInformationEntity

protected abstract void extendInsertStatementStringWithPersonNameSearchValuesForSelectedInformationEntity(StringBuffer b,
                                                                                                          AttributeList list,
                                                                                                          InformationEntity ie)
                                                                                                   throws DicomException

Extend a SQL INSERT statement in the process of being constructed with the values of the additional search columns derived from person name attributes in the instance for the entity.

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which a select statement is being constructed

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendStatementStringWithMatchingAttributesForSelectedInformationEntity

protected abstract void extendStatementStringWithMatchingAttributesForSelectedInformationEntity(StringBuffer b,
                                                                                                AttributeList list,
                                                                                                InformationEntity ie)
                                                                                         throws DicomException

Extend a SQL SELECT statement in the process of being constructed with matching clauses for the unique keys of the entity and all its parents.

For example, a model might specify the unique key for the patient to be PatientID, the study to be StudyInstanceUID, the series to be SeriesInstanceUID and so on. A match requested at the series level would then require PatientID, StudyInstanceUID and SeriesInstanceUID to match what was in the supplied AttributeList

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which a select statement is being constructed

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendInsertStatementStringWithAttributeNamesForSelectedInformationEntity

protected abstract void extendInsertStatementStringWithAttributeNamesForSelectedInformationEntity(StringBuffer b,
                                                                                                  AttributeList list,
                                                                                                  InformationEntity ie)
                                                                                           throws DicomException

Extend a SQL INSERT statement in the process of being constructed with the names of the attributes in the instance for the entity.

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which an insert statement is being constructed

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendInsertStatementStringWithAttributeValuesForSelectedInformationEntity

protected abstract void extendInsertStatementStringWithAttributeValuesForSelectedInformationEntity(StringBuffer b,
                                                                                                   AttributeList list,
                                                                                                   InformationEntity ie,
                                                                                                   String fileName)
                                                                                            throws DicomException

Extend a SQL INSERT statement in the process of being constructed with the values of the attributes in the instance for the entity.

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which an insert statement is being constructed

fileName - the local filename, which may be non-null for INSTANCE level insertions

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendInsertStatementStringWithDerivedAttributeNamesForSelectedInformationEntity

protected abstract void extendInsertStatementStringWithDerivedAttributeNamesForSelectedInformationEntity(StringBuffer b,
                                                                                                         AttributeList list,
                                                                                                         InformationEntity ie)
                                                                                                  throws DicomException

Extend a SQL INSERT statement in the process of being constructed with the names of the derived attributes in the instance for the entity.

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which an insert statement is being constructed

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

extendInsertStatementStringWithDerivedAttributeValuesForSelectedInformationEntity

protected abstract void extendInsertStatementStringWithDerivedAttributeValuesForSelectedInformationEntity(StringBuffer b,
                                                                                                          AttributeList list,
                                                                                                          InformationEntity ie)
                                                                                                   throws DicomException

Extend a SQL INSERT statement in the process of being constructed with the values of the derived attributes in the instance for the entity.

Called when inserting a new record for an instance of the entity.

Specific to each concrete information model extending DatabaseInformationModel.

Parameters:

b - the statement being constructed

list - the DICOM attributes of a composite object, containing the attributes describing this instance of the entity

ie - the InformationEntity for which an insert statement is being constructed

Throws:

DicomException - thrown if there are problems extracting the DICOM attributes

createPrimaryKeyForSelectedInformationEntity

protected abstract String createPrimaryKeyForSelectedInformationEntity(InformationEntity ie)

Create a new unique key which may be used to identify a new instance of an entity.

Called when inserting a new record for an instance of the entity.

Parameters:

ie - the InformationEntity for which a key is requested

Returns:

string value of a unique key

updateSelectedRecord

public void updateSelectedRecord(InformationEntity ie,
                                 String localPrimaryKeyValue,
                                 String key,
                                 String value)
                          throws DicomException

For a particular instance of an information entity, update the record in the database table with a new value for the specified attribute (column).

For example, for the study entity, this would update an attribute of a particular study, for example the StudyID attribute.

Parameters:

ie - the InformationEntity of the record to be updated

localPrimaryKeyValue - the string value of the unique key which identifies the instance of the entity (not including wildcards)

key - the string name of the attribute (column) to be set (updated)

value - the string value to set

Throws:

DicomException - thrown if the update fails

deleteSelectedRecord

public void deleteSelectedRecord(InformationEntity ie,
                                 String localPrimaryKeyValue)
                          throws DicomException

For a particular instance of an information entity, delete the record from the database table.

For example, for the study entity, this would delete a particular study.

Note that this method does not delete any referenced files, for example in the case of an instance record.

Parameters:

ie - the InformationEntity of the record to be returned

localPrimaryKeyValue - the string value of the unique key which identifies the instance of the entity (not including wildcards)

Throws:

DicomException - thrown if the deletion fails

findAllAttributeValuesForSelectedRecord

public Map findAllAttributeValuesForSelectedRecord(InformationEntity ie,
                                                   String localPrimaryKeyValue)
                                            throws DicomException

For a particular instance of an information entity, get the values of all the columns in the entity's database table.

For example, for the study entity, this would return the attributes for a particular study.

Parameters:

ie - the InformationEntity of the record to be returned

localPrimaryKeyValue - the string value of the unique key which identifies the instance of the entity (not including wildcards)

Returns:

a TreeMap of String values indexed by String column names

Throws:

DicomException - thrown if the query fails

findAllAttributeValuesForAllRecordsForThisInformationEntity

public ArrayList findAllAttributeValuesForAllRecordsForThisInformationEntity(InformationEntity ie)
                                                                      throws DicomException

For all records of an information entity, get the values of all the columns in the entity's database table.

For example, for the study entity, this would return the attributes for all the studies in the database.

Parameters:

ie - the InformationEntity of the records to be returned

Returns:

an ArrayList of records, each value of which is a TreeMap of String values indexed by String column names

Throws:

DicomException - thrown if the query fails

findAllAttributeValuesForAllRecordsForThisInformationEntityWithSpecifiedUID

public ArrayList findAllAttributeValuesForAllRecordsForThisInformationEntityWithSpecifiedUID(InformationEntity ie,
                                                                                             String uid)
                                                                                      throws DicomException

For all records of an information entity matching the specified UID, get the values of all the columns in the entity's database table.

For example, for the study entity, this would return the attributes for all the studies with the specified UID in the database.

For the instance entity, this would return the attributes for all the instances with the specified UID in the database.

In an ideal world, this method should only ever return one record, since the DICOM model is predicated on UIDs being unique !

Parameters:

ie - the InformationEntity of the records to be returned

uid - the String UID of the records to be returned

Returns:

an ArrayList of records, each value of which is a TreeMap of String values indexed by String column names

Throws:

DicomException - thrown if the query fails

findAllAttributeValuesForAllRecordsForThisInformationEntityWithSpecifiedParent

public ArrayList findAllAttributeValuesForAllRecordsForThisInformationEntityWithSpecifiedParent(InformationEntity ie,
                                                                                                String localParentReference)
                                                                                         throws DicomException

For all records of an information entity with the specified parent, get the values of all the columns in the entity's database table.

For example, for the series entity, this would return the attributes for all the series of a particular study (parent).

Parameters:

ie - the InformationEntity of the records to be returned

localParentReference - the string value of the unique key which identifies the instance of the parent entity (not including wildcards)

Returns:

an ArrayList of records, each value of which is a TreeMap of String values indexed by String column names

Throws:

DicomException - thrown if the query fails

findAllAttributeValuesForAllRecordsForThisInformationEntityWithMatchingParent

public ArrayList findAllAttributeValuesForAllRecordsForThisInformationEntityWithMatchingParent(InformationEntity ieWanted,
                                                                                               InformationEntity ieParent,
                                                                                               String parentMatchingAttribute,
                                                                                               String parentMatchingValue)
                                                                                        throws DicomException

For all records of an information entity with all parents matching a particular attribute value, get the values of all attributes.

For example, for the instance entity, this could return the instance local file name for all the series (parents) with a particular frame of reference UID.

Parameters:

ieWanted - the InformationEntity of the record level of the attribute to be returned

ieParent - the