org.dspace.browse
Interface BrowseCreateDAO

All Known Implementing Classes:

BrowseCreateDAOOracle, BrowseCreateDAOPostgres, SolrBrowseCreateDAO

public interface BrowseCreateDAO

Interface for any class wishing to provide a browse storage later. This particular Data Access Object deals with building and destroying the database, and inserting and removing content from it. There is an alternative class BrowseDAO which deals with Read-Only operations. If you implement this class, and you wish it to be loaded via the BrowseDAOFactory you must supply a constructor of the form: public BrowseCreateDAOImpl(Context context) {} Where Context is the DSpace Context object Where tables are referred to in this class, they can be obtained from the BrowseIndex class, which will answer queries given the context of the request on which table is the relevant target.

Author:

Richard Jones

Method Summary

String	createCollectionView(String table, String view, boolean execute) Create the View of the full item index as seen from a collection.
String	createCommunityView(String table, String view, boolean execute) Create the View of the full item index as seen from a community If the boolean execute is true this operation should be carried out, and if it is false it should not.
String[]	createDatabaseIndices(String table, List<Integer> sortCols, boolean value, boolean execute) Create any indices that the implementing DAO sees fit to maximise performance.
String	createDistinctMap(String table, String map, boolean execute) Create a table to hold a mapping between an item and a distinct metadata value that can appear across multiple items (for example, author names).
String	createDistinctTable(String table, boolean execute) Create the table which will hold the distinct metadata values that appear in multiple items.
String[]	createMapIndices(String disTable, String mapTable, boolean execute) Create any indices that the implementing DAO sees fit to maximise performance.
String	createPrimaryTable(String table, List<Integer> sortCols, boolean execute) Create the main index table.
String	createSequence(String sequence, boolean execute) Create the sequence with the given name.
void	deleteByItemID(String table, int itemID) Delete the record for the given item id from the specified table.
void	deleteCommunityMappings(int itemID)
List<Integer>	deleteMappingsByItemID(String mapTable, int itemID)
String	dropIndexAndRelated(String table, boolean execute) Drop the given table name, and all other resources that are attached to it.
String	dropSequence(String sequence, boolean execute) Drop the given sequence name.
String	dropView(String view, boolean execute) Drop the given view name.
int	getDistinctID(String table, String value, String authority, String sortValue) Get the browse index's internal id for the location of the given string and sort value in the given table.
int	insertDistinctRecord(String table, String value, String authority, String sortValue) Insert the given value and sort value into the distinct index table.
void	insertIndex(String table, int itemID, Map<Integer,String> sortCols) Insert an index record into the given table for the given item id.
void	pruneDistinct(String table, String map, List<Integer> distinctIds) So that there are no distinct values indexed which are no longer referenced from the map table, this method checks for values which are not referenced from the map, and removes them.
void	pruneExcess(String table, boolean withdrawn) So that any left over indices for items which have been deleted can be assured to have been removed, this method checks for indices for items which are not in the item table.
void	pruneMapExcess(String map, boolean withdrawn, List<Integer> distinctIds) So that any left over indices for items which have been deleted can be assured to have been removed, this method checks for indices for items which are not in the item table.
boolean	testTableExistence(String table) Find out of a given table exists.
void	updateCommunityMappings(int itemID)
org.dspace.browse.MappingResults	updateDistinctMappings(String table, int itemID, Set<Integer> distinctIDs) Update a mapping between an item id and a distinct metadata field such as an author, who can appear in multiple items.
boolean	updateIndex(String table, int itemID, Map<Integer,String> sortCols) Updates an index record into the given table for the given item id.

Method Detail

deleteByItemID

void deleteByItemID(String table,
                    int itemID)
                    throws BrowseException

Delete the record for the given item id from the specified table. Table names can be obtained from the BrowseIndex class

Parameters:

table - the browse table to remove the index from

itemID - the database id of the item to remove the index for

Throws:

BrowseException

deleteCommunityMappings

void deleteCommunityMappings(int itemID)
                             throws BrowseException

Throws:

BrowseException

updateCommunityMappings

void updateCommunityMappings(int itemID)
                             throws BrowseException

Throws:

BrowseException

insertIndex

void insertIndex(String table,
                 int itemID,
                 Map<Integer,String> sortCols)
                 throws BrowseException

Insert an index record into the given table for the given item id. The Map should contain key value pairs representing the sort column integer representation and the normalised value for that field. For example, the caller might do as follows: Map map = new HashMap(); map.put(new Integer(1), "the title"); map.put(new Integer(2), "the subject"); BrowseCreateDAO dao = BrowseDAOFactory.getCreateInstance(); dao.insertIndex("index_1", 21, map);

Parameters:

table - the browse table to insert the index in

itemID - the database id of the item being indexed

sortCols - an Integer-String map of sort column numbers and values

Throws:

BrowseException

updateIndex

boolean updateIndex(String table,
                    int itemID,
                    Map<Integer,String> sortCols)
                    throws BrowseException

Updates an index record into the given table for the given item id. The Map should contain key value pairs representing the sort column integer representation and the normalised value for that field. For example, the caller might do as follows: Map map = new HashMap(); map.put(new Integer(1), "the title"); map.put(new Integer(2), "the subject"); BrowseCreateDAO dao = BrowseDAOFactory.getCreateInstance(); dao.updateIndex("index_1", 21, map);

Parameters:

table - the browse table to insert the index in

itemID - the database id of the item being indexed

sortCols - an Integer-String map of sort column numbers and values

Returns:

true if the record is updated, false if not found

Throws:

BrowseException

getDistinctID

int getDistinctID(String table,
                  String value,
                  String authority,
                  String sortValue)
                  throws BrowseException

Get the browse index's internal id for the location of the given string and sort value in the given table. This method should always return a positive integer, as if no existing ID is available for the given value then one should be inserted using the data supplied, and the ID returned. Generally this method is used in conjunction with createDistinctMapping thus: BrowseCreateDAO dao = BrowseDAOFactory.getCreateInstance(); dao.createDistinctMapping("index_1_distinct_map", 21, dao.getDistinctID("index_1_distinct", "Human Readable", "human readable")); When it creates a distinct record, it would usually do so through insertDistinctRecord defined below.

Parameters:

table - the table in which to look for/create the id

value - the value on which to search

sortValue - the sort value to use in case of the need to create

Returns:

the database id of the distinct record

Throws:

BrowseException

insertDistinctRecord

int insertDistinctRecord(String table,
                         String value,
                         String authority,
                         String sortValue)
                         throws BrowseException

Insert the given value and sort value into the distinct index table. This returns an integer which represents the database id of the created record, so that it can be used, for example in createDistinctMapping thus: BrowseCreateDAO dao = BrowseDAOFactory.getCreateInstance(); dao.createDistinctMapping("index_1_distinct_map", 21, dao.insertDistinctRecord("index_1_distinct", "Human Readable", "human readable")); This is less good than using getDistinctID defined above, as if there is already a distinct value in the table it may throw an exception

Parameters:

table - the table into which to insert the record

value - the value to insert

sortValue - the sort value to insert

Returns:

the database id of the created record

Throws:

BrowseException

updateDistinctMappings

org.dspace.browse.MappingResults updateDistinctMappings(String table,
                                                        int itemID,
                                                        Set<Integer> distinctIDs)
                                                        throws BrowseException

Update a mapping between an item id and a distinct metadata field such as an author, who can appear in multiple items. To get the id of the distinct record you should use either getDistinctID or insertDistinctRecord as defined above.

Parameters:

table - the mapping table

itemID - the item id

distinctIDs - the id of the distinct record

Returns:

the ids of any distinct records that have been unmapped

Throws:

BrowseException

testTableExistence

boolean testTableExistence(String table)
                           throws BrowseException

Find out of a given table exists.

Parameters:

table - the table to test

Returns:

true if exists, false if not

Throws:

BrowseException

dropIndexAndRelated

String dropIndexAndRelated(String table,
                           boolean execute)
                           throws BrowseException

Drop the given table name, and all other resources that are attached to it. In normal relational database land this will include constraints and views. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen).

Parameters:

table - The table to drop

execute - Whether to action the removal or not

Returns:

The instructions (SQL) that effect the removal

Throws:

BrowseException

dropSequence

String dropSequence(String sequence,
                    boolean execute)
                    throws BrowseException

Drop the given sequence name. This is relevant to most forms of database, but not all. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen)

Parameters:

sequence - the sequence to drop

execute - whether to action the removal or not

Returns:

The instructions (SQL) that effect the removal

Throws:

BrowseException

dropView

String dropView(String view,
                boolean execute)
                throws BrowseException

Drop the given view name. This is relevant to most forms of database, but not all. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen)

Parameters:

view - the view to drop

execute - whether to action the removal or not

Returns:

The instructions (SQL) that effect the removal

Throws:

BrowseException

createSequence

String createSequence(String sequence,
                      boolean execute)
                      throws BrowseException

Create the sequence with the given name. This is relevant to most forms of database, but not all. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen)

Parameters:

sequence - the sequence to create

execute - whether to action the create or not

Returns:

the instructions (SQL) that effect the creation

Throws:

BrowseException

createPrimaryTable

String createPrimaryTable(String table,
                          List<Integer> sortCols,
                          boolean execute)
                          throws BrowseException

Create the main index table. This is the one which will contain a single row per item. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen) This form is used for the primary item browse tables This should be used, for example, like this: List list = new ArrayList(); list.add(new Integer(1)); list.add(new Integer(2)); BrowseCreateDAO dao = BrowseDAOFactory.getCreateInstance(); dao.createPrimaryTable("index_1", list, true);

Parameters:

table - the raw table to create

sortCols - a List of Integers numbering the sort columns required

execute - whether to action the create or not

Returns:

the instructions (SQL) that effect the creation

Throws:

BrowseException

createDatabaseIndices

String[] createDatabaseIndices(String table,
                               List<Integer> sortCols,
                               boolean value,
                               boolean execute)
                               throws BrowseException

Create any indices that the implementing DAO sees fit to maximise performance. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string array should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen). It's an array so that you can return each bit of SQL as an element if you want.

Parameters:

table - the table upon which to create indices

sortCols - TODO

execute - whether to action the create or not

Returns:

the instructions (SQL) that effect the indices

Throws:

BrowseException

createMapIndices

String[] createMapIndices(String disTable,
                          String mapTable,
                          boolean execute)
                          throws BrowseException

Create any indices that the implementing DAO sees fit to maximise performance. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string array should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen). It's an array so that you can return each bit of SQL as an element if you want.

Parameters:

disTable - the distinct table upon which to create indices

mapTable - the mapping table upon which to create indices

execute - whether to action the create or not

Returns:

the instructions (SQL) that effect the indices

Throws:

BrowseException

createCollectionView

String createCollectionView(String table,
                            String view,
                            boolean execute)
                            throws BrowseException

Create the View of the full item index as seen from a collection. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string array should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen).

Parameters:

table - the table to create the view on

view - the name of the view to create

execute - whether to action the create or not

Returns:

the instructions (SQL) that effects the create

Throws:

BrowseException

createCommunityView

String createCommunityView(String table,
                           String view,
                           boolean execute)
                           throws BrowseException

Create the View of the full item index as seen from a community If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string array should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen).

Parameters:

table - the table to create the view on

view - the name of the view to create

execute - whether to action the create or not

Returns:

the instructions (SQL) that effects the create

Throws:

BrowseException

deleteMappingsByItemID

List<Integer> deleteMappingsByItemID(String mapTable,
                                     int itemID)
                                     throws BrowseException

Throws:

BrowseException

createDistinctTable

String createDistinctTable(String table,
                           boolean execute)
                           throws BrowseException

Create the table which will hold the distinct metadata values that appear in multiple items. For example, this table may hold a list of unique authors, each name in the metadata for the entire system appearing only once. Or for subject classifications. If the boolean execute is true this operation should be carried out, and if it is false it should not. The returned string array should contain the SQL (if relevant) that the caller can do with what they like (for example, output to the screen).

Parameters:

table - the table to create

execute - whether to action the create or not

Returns:

the instructions (SQL) that effects the create

Throws:

BrowseException

createDistinctMap

String createDistinctMap(String table,
                         String map,
                         boolean execute)
                         throws BrowseException

Create a table to hold a mapping between an item and a distinct metadata value that can appear across multiple items (for example, author names). If the boolean execute is true this operation should be carried out, and if it is false it should not.

Parameters:

table - the name of the distinct table which holds the target of the mapping

map - the name of the mapping table itself

execute - whether to execute the query or not

Returns:

Throws:

BrowseException

pruneExcess

void pruneExcess(String table,
                 boolean withdrawn)
                 throws BrowseException

So that any left over indices for items which have been deleted can be assured to have been removed, this method checks for indices for items which are not in the item table. If it finds an index which does not have an associated item it removes it.

Parameters:

table - the index table to check

withdrawn - TODO

Throws:

BrowseException

pruneMapExcess

void pruneMapExcess(String map,
                    boolean withdrawn,
                    List<Integer> distinctIds)
                    throws BrowseException

So that any left over indices for items which have been deleted can be assured to have been removed, this method checks for indices for items which are not in the item table. If it finds an index which does not have an associated item it removes it.

Parameters:

map - the name of the associated distinct mapping table

withdrawn - TODO

Throws:

BrowseException

pruneDistinct

void pruneDistinct(String table,
                   String map,
                   List<Integer> distinctIds)
                   throws BrowseException

So that there are no distinct values indexed which are no longer referenced from the map table, this method checks for values which are not referenced from the map, and removes them.

Parameters:

table - the name of the distinct index table

map - the name of the associated distinct mapping table.

Throws:

BrowseException