public abstract class WritableDatabaseService extends DatabaseService
AnnotatedPluginDocument.toXMLExcludingInternalPluginDocument() AnnotatedPluginDocument.getDocumentOrNull().toXML() DocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element,com.biomatters.geneious.publicapi.documents.ElementProvider,URN) AnnotatedPluginDocument.setDatabase(DatabaseService)
before exposing that document to any external code. This includes adding documents, removing documents, loading documents, moving documents, and loading/setting folder view documents.
An implementation also needs to handle referenced documents:
AnnotatedPluginDocument.getReferencedDocuments().
For each of the referenced documents already in the database hierarchy, it should increment a reference count to those documents.
For reference documents not already in this database, it should add a copy of the reference document to an invisible region of the database.
| Modifier and Type | Class and Description |
|---|---|
static class |
WritableDatabaseService.DummyService
A dummy implementation of WritableDatabaseService that provides no functionality apart from a name and icons
|
static interface |
WritableDatabaseService.SearchResultPropertiesAdjuster |
DatabaseService.SequenceSearchQueryTypeGeneiousService.ServiceStatus| Modifier and Type | Field and Description |
|---|---|
static String |
KEY_SEARCH_SUBFOLDERS
All WritableDatabaseServices return a
CheckboxSearchOption
with this code from getExtendedSearchOptions() |
static String |
KEY_SEARCH_TYPE
All WritableDatabaseServices return a
TextOrSimilaritySearchOption
with this code from getExtendedSearchOptions(false) |
| Modifier | Constructor and Description |
|---|---|
protected |
WritableDatabaseService() |
| Modifier and Type | Method and Description |
|---|---|
protected abstract AnnotatedPluginDocument |
_addDocumentCopy(AnnotatedPluginDocument annotatedDocument,
ProgressListener progress)
Implementaion method for
addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
that subclasses should implement. |
protected AnnotatedPluginDocument |
_addDocumentCopyWithProperties(AnnotatedPluginDocument document,
ProgressListener progress,
Map<String,Object> properties)
|
protected AnnotatedPluginDocument |
_addDocumentCopyWithProperties(AnnotatedPluginDocument document,
ProgressListener progress,
Map<String,Object> properties,
URN urnToUseForAddedDocument)
|
protected abstract AnnotatedPluginDocument |
_addReferencedOnlyDocumentCopy(AnnotatedPluginDocument annotatedDocument,
ProgressListener progress)
This method is only called from the helper method
duplicateDocumentAndDealWithReferencedDocuments(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, com.biomatters.geneious.publicapi.documents.ElementProvider, java.util.concurrent.atomic.AtomicReference, com.biomatters.geneious.publicapi.documents.URN). |
protected boolean |
_canRemoveChildFolder(String name)
Sub-classes may override this method to make
canRemoveChildFolder(String) prevent folders from being removed. |
protected List<GeneiousAction> |
_getActionsEnabledWhenServiceSelected()
Sub-classes should override this to provide actions as defined by
GeneiousService.getActionsEnabledWhenServiceSelected(). |
static ExtendedSearchOption[] |
_getExtendedSearchOptions(boolean isAdvancedSearch)
Get the extended options that most WritableDatabaseServices return from
getExtendedSearchOptions(boolean). |
protected AnnotatedPluginDocument |
_getFolderViewDocument()
The implementation method for
getFolderViewDocument(). |
protected abstract String |
_getHelp()
Sub-classes should override this to provide help as defined by
GeneiousService.getHelp()
Ths results of this method are combined with any
additional help provided to addAdditionalHelp(String)
to create the results for getHelp(). |
protected abstract WritableDatabaseService |
_getHiddenFolder(String folderName,
boolean isPerUserFolder)
The implementation method for
getHiddenFolder(String, boolean) |
protected abstract Icons |
_getIcons()
Sub-classes should override this to provide icons as defined by
GeneiousService.getIcons(). |
protected abstract boolean |
_moveDocument(AnnotatedPluginDocument document,
ProgressListener progress)
Implementation method for
moveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
that subclasses should implement. |
protected abstract void |
_removeDocument(AnnotatedPluginDocument document,
ProgressListener progress)
Implementation method for
removeDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
that subclasses should implement. |
protected void |
_retrieve(AnnotatedPluginDocument[] summaryDocuments,
RetrieveCallback callback,
URN[] urnsToNotRetrieve)
Implementaion method for
retrieve(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[])
that subclasses should implement. |
protected abstract void |
_retrieve(Query query,
RetrieveCallback callback,
URN[] urnsToNotRetrieve)
Implementaion method for
retrieve(com.biomatters.geneious.publicapi.databaseservice.Query, com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[])
that subclasses should implement. |
protected abstract void |
_retrieve(URN[] urnsToRetrieve,
RetrieveCallback callback)
Implementaion method for
retrieve(com.biomatters.geneious.publicapi.documents.URN[], com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback)
that subclasses should implement. |
void |
addAdditionalAction(GeneiousAction action)
Adds an additional action that this service will provide
via
getActionsEnabledWhenServiceSelected() |
void |
addAdditionalHelp(String additionalHelpText)
Add some additional help to append to the end of the standard help this folder
returned from
getHelp() |
void |
addDatabaseServiceListener(DatabaseServiceListener listener)
A sub-class must not override this, but should instead
use
getDatabaseServiceListeners() as this
class relies on getDatabaseServiceListeners(). |
AnnotatedPluginDocument |
addDocumentCopy(AnnotatedPluginDocument document,
ProgressListener progress)
Add a copy of this document to this database.
|
AnnotatedPluginDocument |
addDocumentCopyWithProperties(AnnotatedPluginDocument document,
ProgressListener progress,
Map<String,Object> properties)
|
AnnotatedPluginDocument |
addDocumentCopyWithProperties(AnnotatedPluginDocument document,
ProgressListener progress,
Map<String,Object> properties,
URN urnToUseForAddedDocument)
Add a copy of this document to this database with additional properties that
will show up as associated with this document on any future queries while the document resides in this folder.
|
abstract String |
addHiddenElement(org.jdom.Element newElement,
ProgressListener progress)
Adds a new hidden element to this database and generates a new unique name
which is returned.
|
abstract void |
addHiddenElement(String name,
org.jdom.Element newElement,
ProgressListener progress)
adds a new hidden element to this database using the given name.
|
void |
addOverlayIcons(Icons icons)
add an icon which will be drawn on top of the standard database icon
|
void |
addSearchResultPropertiesAdjuster(WritableDatabaseService.SearchResultPropertiesAdjuster propertiesAdjuster)
Add a SearchResultPropertiesAdjuster to this database service.
|
protected boolean |
allowChangingFolderProperties()
Are the properties of this folder allowed to be changed ( moving, renaming, deleting)
|
abstract boolean |
canMoveTo(WritableDatabaseService destination)
Can this entire database folder be moved to this new location?
The default implementation always returns false.
|
boolean |
canRemoveChildFolder(String name)
Can the child folder with this name be removed.
|
abstract boolean |
containsDocumentAnywhereWithinDatabase(URN documentURN)
Determine if this database (including any other folders and any user invisible
folders) contains a document with this URN
This method should return the same information no matter where in the
DatabaseService tree it is called.
|
abstract WritableDatabaseService |
createChildFolder(String name)
Creates a child DatabaseService.
|
WritableDatabaseService |
createFolderViewFolder(String folderName,
AnnotatedPluginDocument folderViewDocument)
Creates a new child folder that contains a document that may be displayed for representing an entire view of the folder.
|
URN |
createUrnForDocumentSoonToBeAdded()
Returns a URN which can be specified as used for document later added to this database using
addDocumentCopyWithProperties(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener, java.util.Map, com.biomatters.geneious.publicapi.documents.URN). |
protected AnnotatedPluginDocument |
duplicateDocumentAndDealWithReferencedDocuments(AnnotatedPluginDocument document,
ElementProvider pluginDocumentElementProvider,
AtomicReference<org.jdom.Element> returnedPluginDocumentElement)
Deprecated.
use #duplicateDocumentAndDealWithReferencedDocuments
|
protected AnnotatedPluginDocument |
duplicateDocumentAndDealWithReferencedDocuments(AnnotatedPluginDocument document,
ElementProvider pluginDocumentElementProvider,
AtomicReference<org.jdom.Element> returnedPluginDocumentElement,
URN urnOfNewDocument)
This as a helper method to facilitate implementing
_addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument,jebl.util.ProgressListener). |
List<GeneiousAction> |
getActionsEnabledWhenServiceSelected()
WritableDatabaseService implements this as a final method to add
any additional actions supplied to
addAdditionalAction(com.biomatters.geneious.publicapi.plugin.GeneiousAction)
combined with the actions provided by sub-classes in
_getActionsEnabledWhenServiceSelected(). |
Map<String,ElementProvider> |
getAdditionalPerDocumentXml(AnnotatedPluginDocument document,
List<String> keys,
boolean isPerUser,
ProgressListener progressListener)
Get some additional XML associated with a particular document that has been saved using
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener)
or saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, boolean, java.util.Map, jebl.util.ProgressListener)
This method is similar to getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, jebl.util.ProgressListener)
except that this method allows retrieving multiple additional XML entries with a single method invocation, potentially allowing the database to handle
it more efficiently than multiple calls to getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.List, boolean, jebl.util.ProgressListener) |
org.jdom.Element |
getAdditionalPerDocumentXml(AnnotatedPluginDocument document,
String key,
boolean isPerUser,
ProgressListener progressListener)
Get some additional XML associated with a particular document that has been saved using
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener). |
List<String> |
getAdditionalPerDocumentXmlKeys(boolean isPerUser,
ProgressListener progressListener)
Get a list of all keys that additional XML has been stored under on any document.
|
protected String |
getAssignerForCreatingUrn() |
WritableDatabaseService |
getChildService(String name)
Gets a child service whose
getFolderName() == name. |
Color |
getColor(boolean loadNow)
Gets the text/icon color for this folder
|
WritableDatabaseService |
getDatabaseRoot()
Get the root folder of this database folder hierarchy.
|
protected List<DatabaseServiceListener> |
getDatabaseServiceListeners()
Get all DatabaseServiceListeners added using
addDatabaseServiceListener(com.biomatters.geneious.publicapi.databaseservice.DatabaseServiceListener). |
AnnotatedPluginDocument |
getDocument(URN urn)
Get a document that exists anywhere within this database (including other folders) with a particular URN.
|
abstract int |
getDocumentCount(boolean includeSubFolders)
Get the number of documents in this folder
|
abstract WritableDatabaseService |
getDocumentLocation(URN documentURN)
If this database contains this document in any user visible folder returns
the WritableDatabaseService representing the folder that contains it.
|
ExtendedSearchOption[] |
getExtendedSearchOptions(boolean isAdvancedSearch)
Provide a list of extended options to be displayed the in the search panel.
|
abstract String |
getFolderName()
Get the name of this DatabaseService folder displayed to the user.
|
AnnotatedPluginDocument |
getFolderViewDocument()
If this folder represents the results of a search, it must provide a
FolderViewDocument which stores all properties of that search.
|
String |
getHelp()
WritableDatabaseService implements this as a final method to add
any additional help supplied to
addAdditionalHelp(String)
combined with the help provided by sub-classes in
_getHelp() |
abstract org.jdom.Element |
getHiddenElement(String elementName,
ProgressListener progress)
get(load) a special hidden element
|
abstract String[] |
getHiddenElementNames()
lists the hidden elements stored in this database.
|
WritableDatabaseService |
getHiddenFolder(String folderName,
boolean isPerUserFolder)
Gets an existing or creates a new hidden folder as an immediate child of the
root service of this database.
|
abstract String[] |
getHiddenFolderNames()
Get a list of hidden folders that can be used as parameters to the getHiddenFolder() method.
|
Icons |
getIcons()
WritableDatabaseService implements this as a final method to add
any additional icons supplied to
addOverlayIcons(com.biomatters.geneious.publicapi.plugin.Icons)
combined with the icons provided by sub-classes in
_getIcons() |
Object |
getLock()
An object used as a lock by this database while it modifies the in memory contents of documents.
|
WritableDatabaseService |
getPrimaryDatabaseRoot()
Returns the database root (see
getDatabaseRoot()) for the primary database in this collection. |
protected abstract String |
getRootUniqueId()
Get the unique ID for the root folder of this database.
|
String |
getUniqueID()
Get a unique ID for this database service.
|
protected void |
initialize(GeneiousServiceListener listener)
Constructor method - initializes the service.
|
boolean |
isDeleted()
Get whether this database folder is deleted.
|
boolean |
isLocal()
Is this a local database rather than a shared Database.
|
boolean |
isReadOnly()
Returns whether or not this folder is read only.
|
boolean |
moveDocument(AnnotatedPluginDocument document,
ProgressListener progress)
Move a document that currently reside elsewhere in this database to this folder.
|
abstract void |
moveTo(WritableDatabaseService destination)
Move this entire database folder to a new location.
|
void |
removeAdditionalAction(GeneiousAction action)
Removes an additional action (added previously using
addAdditionalAction(com.biomatters.geneious.publicapi.plugin.GeneiousAction))
that this service provides. |
void |
removeAdditionalHelp(String additionalHelpText)
Removed some additional help added using
addAdditionalHelp(String) |
abstract void |
removeChildFolder(String folderName)
Removes a child folder with this folder name.
|
void |
removeChildFolder(String folderName,
ProgressListener progressListener)
Removes a child folder with this folder name.
|
void |
removeDatabaseServiceListener(DatabaseServiceListener listener)
A sub-class must not override this, but should instead
use
getDatabaseServiceListeners() as this
class relies on getDatabaseServiceListeners(). |
void |
removeDocument(AnnotatedPluginDocument document,
ProgressListener progress)
Remove a document from this database.
|
abstract void |
removeHiddenElement(String name)
removes a hidden element.
|
void |
removeOverlayIcons(Icons icons)
remove an icon added using
addOverlayIcons(com.biomatters.geneious.publicapi.plugin.Icons) |
void |
removeSearchResultPropertiesAdjuster(WritableDatabaseService.SearchResultPropertiesAdjuster propertiesAdjuster)
Removed a SearchResultPropertiesAdjuster added via
addSearchResultPropertiesAdjuster(com.biomatters.geneious.publicapi.databaseservice.WritableDatabaseService.SearchResultPropertiesAdjuster). |
abstract void |
renameFolder(String newName)
Rename this folder.
|
void |
retrieve(AnnotatedPluginDocument[] documents,
RetrieveCallback callback,
URN[] urnsToNotRetrieve)
Retrieves full documents corresponding to the given summary documents from the
database.
|
void |
retrieve(Query query,
RetrieveCallback callback,
URN[] urnsToNotRetrieve)
Get documents by searching a database.
|
void |
retrieve(URN[] urnsToRetrieve,
RetrieveCallback callback)
Retrieve documents with the specified URNs.
|
void |
saveAdditionalPerDocumentXml(AnnotatedPluginDocument document,
boolean isPerUser,
Map<String,ElementProvider> elementProviders,
ProgressListener progressListener)
Save some additional XML associated with a particular document.
|
void |
saveAdditionalPerDocumentXml(AnnotatedPluginDocument document,
String key,
boolean isPerUser,
org.jdom.Element element,
ProgressListener progressListener)
Save some additional XML associated with a particular document.
|
abstract boolean |
saveDocument(AnnotatedPluginDocument document,
boolean onlyAnnotatedDocumentHasChanged,
ProgressListener progress)
A document that is already in this database has been modified in memory and should now be saved to permanent storage.
|
void |
setAllowChangingFolderProperties(boolean allow)
Prevent this folder from being moved, renamed or removed.
|
void |
setColor(Color newColor)
Sets the text/icon color for this folder
|
void |
setFolderViewDocument(AnnotatedPluginDocument folderViewDocument,
ProgressListener progressListener)
Sets the folder view document on this folder.
|
abstract void |
updateHiddenElement(String name,
org.jdom.Element newElement,
ProgressListener progress)
updates the contents of a hidden element.
|
void |
waitForSearchIndexingToComplete()
It it permissable for a database to not return documents from a search that have been recently
added to the database due to it still indexing those documents for search purposes.
|
addWeakDatabaseServiceListener, batchSequenceSearch, getDocumentTypesForSequenceSearch, getSearchFields, getSequenceSearchOptions, getSequenceSearchPrograms, isBrowsable, locateSummaryDocument, resumeSearch, retrieve, retrieve, retrieve, sequenceSearch_shutdown, addGeneiousServiceListener, addWeakGeneiousServiceListener, canShutdown, getActionsAlwaysEnabled, getChildServices, getDescription, getFullPath, getGeneiousServiceListener, getName, getParentService, getPreferences, getServiceTreeLabel, getStatus, hasShutdownOrStartedShuttingDown, initializeService, isProOnly, removeGeneiousServiceListener, showInServiceTree, shutdown, toStringpublic static final String KEY_SEARCH_TYPE
TextOrSimilaritySearchOption
with this code from getExtendedSearchOptions(false)public static final String KEY_SEARCH_SUBFOLDERS
CheckboxSearchOption
with this code from getExtendedSearchOptions()public final AnnotatedPluginDocument addDocumentCopy(AnnotatedPluginDocument document, ProgressListener progress) throws DatabaseServiceException
AnnotatedPluginDocument.getStronglyReferencedDocuments())
should the reference counted so that if the reference documents are removed they remain in the database but remain hidden
from the user until they are no longer referenced.document - the document to add a copy ofprogress - reports progressDatabaseServiceExceptionprotected abstract AnnotatedPluginDocument _addDocumentCopy(AnnotatedPluginDocument annotatedDocument, ProgressListener progress) throws DatabaseServiceException
addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
that subclasses should implement.
The implementation must create a copy of the given annotatedDocument that has a different URN from the given annotatedDocument.
This could be done like this:
Element annotatedDocumentXML= annotatedDocument.toXMLExcludingInternalPluginDocument();
AnnotatedPluginDocument annotatedDocumentCopy= DocumentUtilities.createAnnotatedPluginDocument(annotatedDocumentXML,pluginDocumentElementProvider,true);
but that doesn't deal with the complexities of referenced documents. Instead,
the helper method duplicateDocumentAndDealWithReferencedDocuments(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, com.biomatters.geneious.publicapi.documents.ElementProvider, java.util.concurrent.atomic.AtomicReference, com.biomatters.geneious.publicapi.documents.URN)
should be used.DatabaseServiceExceptionprotected String getAssignerForCreatingUrn()
URN.assigner field for newly created documents in this database.public WritableDatabaseService getPrimaryDatabaseRoot()
getDatabaseRoot()) for the primary database in this collection.
For example when this is called on the local "Search Results" (which is a database root), it will return the root "Local Documents" folder.
There should be a single primary database root for all databases that share documents (i.e. all the database folders for which containsDocumentAnywhereWithinDatabase(com.biomatters.geneious.publicapi.documents.URN)) returns true for a given URN)
The default implementation returns getDatabaseRoot() which is correct for any database which has only a single database root.getDatabaseRoot() for the primary database in this collection.getDatabaseRoot()public URN createUrnForDocumentSoonToBeAdded()
addDocumentCopyWithProperties(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener, java.util.Map, com.biomatters.geneious.publicapi.documents.URN).
This is used for example when adding 2 documents to a database that store weak references (see URN.toXMLAsWeakReference(String) to each other. In order for them to reference each other correctly,
they each need to know the URN the other document will have after it is added to the database.addDocumentCopyWithProperties(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener, java.util.Map, com.biomatters.geneious.publicapi.documents.URN)@Deprecated protected final AnnotatedPluginDocument duplicateDocumentAndDealWithReferencedDocuments(AnnotatedPluginDocument document, ElementProvider pluginDocumentElementProvider, AtomicReference<org.jdom.Element> returnedPluginDocumentElement) throws DatabaseServiceException
DatabaseServiceExceptionprotected final AnnotatedPluginDocument duplicateDocumentAndDealWithReferencedDocuments(AnnotatedPluginDocument document, ElementProvider pluginDocumentElementProvider, AtomicReference<org.jdom.Element> returnedPluginDocumentElement, URN urnOfNewDocument) throws DatabaseServiceException
_addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument,jebl.util.ProgressListener).
Duplicates the given document, automatically dealing with referenced documents by
ignoring referenced documents that already exist within this database hierarchy somewhere
and calling _addReferencedOnlyDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
on documents that are not currently within this database hierarchy.
The returned document is a newly generated copy of annotatedDocument.
returnedPluginDocumentElement is used to return the modified internal PluginDocument (it may have
been modified from the original document to handle changed references).
pluginDocumentElementProvider.getElement() will not be called by during this method, but may be called
after the caller has returned from _addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener).
Immediately after calling this method, the caller should save returnedPluginDocumentElement
to persistent storage. pluginDocumentElementProvider should retrieve this value from persistent storage.
It is still up to the caller of this method to reference count documents. Immediately after calling this method,
the caller should use AnnotatedPluginDocument.getStronglyReferencedDocuments()
on the result and increment the reference count on each of those documents. For information on how decrementing
reference counts should be handled, see _removeDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener).
The caller of this method must also set the database on the returned document using AnnotatedPluginDocument.setDatabase(DatabaseService).document - the document to be duplicatedpluginDocumentElementProvider - used after returning from this method for retrieving the internal PluginDocumentreturnedPluginDocumentElement - this is used for returning the internal PluginDocument to the caller.urnOfNewDocument - the URN of the newly added document (which must have been returned from a previous call to createUrnForDocumentSoonToBeAdded() , or null to automatically create one.documentDatabaseServiceException - if the internal PluginDocument of document cannot be loaded or if any of the other methods called by this method throw this exception.protected abstract AnnotatedPluginDocument _addReferencedOnlyDocumentCopy(AnnotatedPluginDocument annotatedDocument, ProgressListener progress) throws DatabaseServiceException
duplicateDocumentAndDealWithReferencedDocuments(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, com.biomatters.geneious.publicapi.documents.ElementProvider, java.util.concurrent.atomic.AtomicReference, com.biomatters.geneious.publicapi.documents.URN).
It should add copy of the given document to an invisible folder independent area of the database. Implementations can do
mostly the same as they do for _addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
except the document is added to an invisible folder independent area of the database rather than a standard folder.
Note: Any implementation must also call copyAdditionalXmlToNewDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument).
An easy way to ensure this is to call addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener) or
addDocumentCopyWithProperties(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener, java.util.Map)
because they will call copyAdditionalXmlToNewDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument)
as part of their implementation.annotatedDocument - the document to copied and addedprogress - reports progressDatabaseServiceExceptionpublic final void removeDocument(AnnotatedPluginDocument document, ProgressListener progress) throws DatabaseServiceException
getDatabaseRoot()) or a hidden folder in that database)
The database implementation of removeDocument must call AnnotatedPluginDocument.setDatabase(null) on the
document if it is successfully removed.document - a document previously returned from either addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
or getDocument(com.biomatters.geneious.publicapi.documents.URN)
or one of the retrieve methods via RetrieveCallback.add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map).progress - to report progress if removing the document takes time.DatabaseServiceExceptionprotected abstract void _removeDocument(AnnotatedPluginDocument document, ProgressListener progress) throws DatabaseServiceException
removeDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
that subclasses should implement.
The implementation must ensure that it deals with referenced documents correctly.
(see duplicateDocumentAndDealWithReferencedDocuments(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, com.biomatters.geneious.publicapi.documents.ElementProvider, java.util.concurrent.atomic.AtomicReference, com.biomatters.geneious.publicapi.documents.URN)).
moveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)setDatabase(null) called on
them before returning from this method. Documents moved to the hidden referenced only documents must have their database set to the root database.
DatabaseServiceExceptionpublic final boolean moveDocument(AnnotatedPluginDocument document, ProgressListener progress) throws DatabaseServiceException
document - the document to be moved. This may be a document that is in an invisible
region of the database (i.e. only referenced by other documents),
in which case it is being moved to a user visible region of the database.progress - reports progressDatabaseServiceExceptionprotected abstract boolean _moveDocument(AnnotatedPluginDocument document, ProgressListener progress) throws DatabaseServiceException
moveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
that subclasses should implement.DatabaseServiceExceptionpublic abstract boolean saveDocument(AnnotatedPluginDocument document, boolean onlyAnnotatedDocumentHasChanged, ProgressListener progress) throws DatabaseServiceException
AnnotatedPluginDocument.save() and AnnotatedPluginDocument.saveDocument().document - the document that has changed. This is the same AnnotatedPluginDocument instance returned from
either addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener)
or getDocument(com.biomatters.geneious.publicapi.documents.URN)
or one of the retrieve methods via RetrieveCallback.add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map).onlyAnnotatedDocumentHasChanged - Sometimes only the AnnotatedPluginDocument rather than the internal PluginDocument has changed. In this
case this parameter is true and the database can perform more efficient storage if it stores the AnnotatedPluginDocument separately from the PluginDocument.
If this parameter is false, both the AnnotatedPluginDocument and the internal PluginDocument should be saved.progress - to report progress if saving the document takes time. The progress listener may also request the save be
cancelled. In this case the DatabaseService should either revert the stored version of the document to its previous state and return false or continue
with saving and return true, whichever is faster. It is not acceptable to leave the stored document in a partially saved state when cancelling.DatabaseServiceException - if the document cannot be saved for any reason.public void saveAdditionalPerDocumentXml(AnnotatedPluginDocument document, String key, boolean isPerUser, org.jdom.Element element, ProgressListener progressListener) throws DatabaseServiceException
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, jebl.util.ProgressListener)
IMPORTANT: When a document is deleted the associated additional XML should be deleted too.document - the document this XML is associated withkey - a unique key that the XML should be stored under (unique to this document but the same key will likely occur on many documents)isPerUser - If true then the XML should only be saved for the current user. If false then the XML should be
stored globally (accessible by all users). This paramater should be ignored by databases that don't allow multiple
simultaneous users.element - the XML data to save. This may be null to delete the existing additional XML associated with the given key.progressListener - for progress reporting and canceling. Never null (use ProgressListener.EMPTY instead).DatabaseServiceException - if the XML couldn't be saved for any reasonsaveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, boolean, java.util.Map, jebl.util.ProgressListener),
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, jebl.util.ProgressListener),
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.List, boolean, jebl.util.ProgressListener)public void saveAdditionalPerDocumentXml(AnnotatedPluginDocument document, boolean isPerUser, Map<String,ElementProvider> elementProviders, ProgressListener progressListener) throws DatabaseServiceException
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener)
except that this method allows storing multiple additional XML entries with a single method invocation, potentially allowing the database to handle
it more efficiently than multiple calls to saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener)document - the document this XML is associated withisPerUser - If true then the XML should only be saved for the current user. If false then the XML should be
stored globally (accessible by all users). This paramater should be ignored by databases that don't allow multiple
simultaneous users.elementProviders - A mapping from a unique key to store the data under to an ElementProvider that can
be used to retrieve the XML element to store. If a null value is specified in the map then the element
corresponding to the specified key will be deleted from the database.progressListener - for progress reporting and canceling. Progress must include retrieving the elements from
the given ElementProviders as well as saving to the database. Never null
(use ProgressListener.EMPTY instead).DatabaseServiceException - if the XML couldn't be saved for any reasonsaveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener),
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, jebl.util.ProgressListener),
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.List, boolean, jebl.util.ProgressListener)public org.jdom.Element getAdditionalPerDocumentXml(AnnotatedPluginDocument document, String key, boolean isPerUser, ProgressListener progressListener) throws DatabaseServiceException
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener).document - the document this XML is associated withkey - the unique key that the XML is stored under (unique to this document but the same key will likely occur on many documents)isPerUser - If true then only return XML which has been stored by passing in true for isPerUser on
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener).
If false then only return XML which has been stored by passing in false to the save method. This paramater should
be ignored by databases that don't allow multiple simultaneous users.progressListener - for progress reporting and canceling. Never null (use ProgressListener.EMPTY instead).DatabaseServiceException - if the XML couldn't be loaded for any reasonsaveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener),
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, boolean, java.util.Map, jebl.util.ProgressListener),
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.List, boolean, jebl.util.ProgressListener)public Map<String,ElementProvider> getAdditionalPerDocumentXml(AnnotatedPluginDocument document, List<String> keys, boolean isPerUser, ProgressListener progressListener) throws DatabaseServiceException
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener)
or saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, boolean, java.util.Map, jebl.util.ProgressListener)
This method is similar to getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, jebl.util.ProgressListener)
except that this method allows retrieving multiple additional XML entries with a single method invocation, potentially allowing the database to handle
it more efficiently than multiple calls to getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.List, boolean, jebl.util.ProgressListener)document - the document this XML is associated withkeys - a list of unique keys that the XML has been stored under (unique to this document but the same key will likely occur on many documents)isPerUser - If true then only return XML which has been stored by passing in true for isPerUser on
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener).
If false then only return XML which has been stored by passing in false to the save method. This paramater should
be ignored by databases that don't allow multiple simultaneous users.progressListener - for progress reporting and canceling. Never null (use ProgressListener.EMPTY instead).ElementProvider that can be used to retrieve the XML data
associated with this document for any elements that were found in the database. If there was no element
associated with a key in the provided list, then there will be no entry in the resulting map.DatabaseServiceException - if providers for the XML couldn't be retrieved for any reasonsaveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener),
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, boolean, java.util.Map, jebl.util.ProgressListener),
getAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, jebl.util.ProgressListener)public List<String> getAdditionalPerDocumentXmlKeys(boolean isPerUser, ProgressListener progressListener) throws DatabaseServiceException
isPerUser - If true return a list of keys for additional XML that has been stored by passing in true for isPerUser on
saveAdditionalPerDocumentXml(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, boolean, org.jdom.Element, jebl.util.ProgressListener).
If false then only return keys which have been stored by passing in false to the save method. This paramater should
be ignored by databases that don't allow multiple simultaneous users.progressListener - for progress reporting and canceling. Never null (use ProgressListener.EMPTY instead).DatabaseServiceExceptionpublic abstract WritableDatabaseService createChildFolder(String name) throws DatabaseServiceException
getChildService(name)
already exists, then this method returns it.name - the name of the child DatabaseService to createDatabaseServiceException - if the folder can't be created.public abstract boolean canMoveTo(WritableDatabaseService destination)
destination - the destination to put this folder inside.moveTo(WritableDatabaseService)public abstract void moveTo(WritableDatabaseService destination) throws DatabaseServiceException
destination.getChildService(folderName).destination - the destination to put this folder inside.DatabaseServiceExceptioncanMoveTo(WritableDatabaseService)public abstract boolean containsDocumentAnywhereWithinDatabase(URN documentURN) throws DatabaseServiceException
documentURN - the URN of the documentDatabaseServiceExceptionpublic abstract WritableDatabaseService getDocumentLocation(URN documentURN) throws DatabaseServiceException
documentURN - the URN of the documentDatabaseServiceExceptionpublic final WritableDatabaseService getChildService(String name)
getFolderName() == name. This method is case insensitive.
WritableDatabaseServices may not have 2 folders with identical names apart from case (even in operating systems that support it
because we want Geneious folder structures to be portable to another OS. For example exporting and importing
entire databases. However, old databases from earlier versions of Geneious may contain folders with identical names apart from case.name - the name of the child service. This may include children of the child by separating names with '/' characters. e.g. childFolderName/grandChildFolderNamegetFolderName() is name or null if one is not found.public final String getUniqueID()
getRootUniqueId()[/FolderName[/FolderName[...]]]getUniqueID in class GeneiousServicepublic abstract String getFolderName()
getUniqueID(), for this folder.protected abstract String getRootUniqueId()
public final AnnotatedPluginDocument getDocument(URN urn) throws DatabaseServiceException
retrieve(com.biomatters.geneious.publicapi.documents.URN[], com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback)urn - the urn of the document to retrieveDatabaseServiceException - if an error occurs while accessing the database.public final void setAllowChangingFolderProperties(boolean allow)
allow - false to prevent this folder from being moved, renamed or removed.protected final boolean allowChangingFolderProperties()
public final boolean canRemoveChildFolder(String name)
name - the name of the child folder to be removed.protected boolean _canRemoveChildFolder(String name)
canRemoveChildFolder(String) prevent folders from being removed.
The default implementation returns true.name - the name of the child folder to be removed.public final WritableDatabaseService getDatabaseRoot()
getPrimaryDatabaseRoot()public boolean isDeleted()
PluginUtilities.getWritableDatabaseServiceRoots()public abstract void removeChildFolder(String folderName) throws DatabaseServiceException
folderName - the name of the child folder to be removed. See getFolderName()DatabaseServiceException - if the folder is unable to be removed for any reason.public void removeChildFolder(String folderName, ProgressListener progressListener) throws DatabaseServiceException
folderName - the name of the child folder to be removed. See getFolderName()progressListener - for reporting progress and cancellingDatabaseServiceException - if the folder is unable to be removed for any reason.public abstract void renameFolder(String newName) throws DatabaseServiceException
parent.getChildService(folderName).
The newly renamed folder may not be available immediately due to delayed firing of listeners. To get the new folder
after calling this method, the calling code should wait (in a non-swing thread) until parent.getChildService(folderName) returns
non-null.newName - the new name of this folderDatabaseServiceException - if the folder is unable to be renamed for any reason.public final void addAdditionalAction(GeneiousAction action)
getActionsEnabledWhenServiceSelected()action - the action to be addedpublic final void removeAdditionalAction(GeneiousAction action)
addAdditionalAction(com.biomatters.geneious.publicapi.plugin.GeneiousAction))
that this service provides.
Note: Currently only works with pop-up menus due to firing of
menus changing for menu bars not being implemented.action - the action to be removedpublic final List<GeneiousAction> getActionsEnabledWhenServiceSelected()
addAdditionalAction(com.biomatters.geneious.publicapi.plugin.GeneiousAction)
combined with the actions provided by sub-classes in
_getActionsEnabledWhenServiceSelected().
Furthermore this method includes a standard set of actions that are available on every WritableDatabaseService.
These actions are: "New folder", "Delete folder", "Rename folder", "Move folder", "Export folder"getActionsEnabledWhenServiceSelected in class GeneiousServiceprotected List<GeneiousAction> _getActionsEnabledWhenServiceSelected()
GeneiousService.getActionsEnabledWhenServiceSelected().
Ths results of this method are combined with any
additional actions provided to addAdditionalAction(com.biomatters.geneious.publicapi.plugin.GeneiousAction)
to create the results for getActionsEnabledWhenServiceSelected().
The default implementation returns an empty list.protected abstract Icons _getIcons()
GeneiousService.getIcons().
Ths results of this method are combined with any
additional overlay icons provided to addOverlayIcons(com.biomatters.geneious.publicapi.plugin.Icons)
to create the results for getIcons().public final Icons getIcons()
addOverlayIcons(com.biomatters.geneious.publicapi.plugin.Icons)
combined with the icons provided by sub-classes in
_getIcons()getIcons in class GeneiousServicepublic final void addOverlayIcons(Icons icons)
public final void removeOverlayIcons(Icons icons)
addOverlayIcons(com.biomatters.geneious.publicapi.plugin.Icons)public final void addAdditionalHelp(String additionalHelpText)
getHelp()additionalHelpText - text which can include HTML tagspublic final void removeAdditionalHelp(String additionalHelpText)
addAdditionalHelp(String)additionalHelpText - the text added using addAdditionalHelp(String)public final String getHelp()
addAdditionalHelp(String)
combined with the help provided by sub-classes in
_getHelp()getHelp in class GeneiousServiceprotected abstract String _getHelp()
GeneiousService.getHelp()
Ths results of this method are combined with any
additional help provided to addAdditionalHelp(String)
to create the results for getHelp().public final void addDatabaseServiceListener(DatabaseServiceListener listener)
getDatabaseServiceListeners() as this
class relies on getDatabaseServiceListeners().addDatabaseServiceListener in class DatabaseServicelistener - a listenerpublic final void removeDatabaseServiceListener(DatabaseServiceListener listener)
getDatabaseServiceListeners() as this
class relies on getDatabaseServiceListeners().removeDatabaseServiceListener in class DatabaseServicelistener - a listenerprotected final List<DatabaseServiceListener> getDatabaseServiceListeners()
addDatabaseServiceListener(com.biomatters.geneious.publicapi.databaseservice.DatabaseServiceListener).getDatabaseServiceListeners in class DatabaseServiceaddDatabaseServiceListener(com.biomatters.geneious.publicapi.databaseservice.DatabaseServiceListener).public final void addSearchResultPropertiesAdjuster(WritableDatabaseService.SearchResultPropertiesAdjuster propertiesAdjuster)
propertiesAdjuster - the SearchResultPropertiesAdjuster to be addedpublic final void removeSearchResultPropertiesAdjuster(WritableDatabaseService.SearchResultPropertiesAdjuster propertiesAdjuster)
addSearchResultPropertiesAdjuster(com.biomatters.geneious.publicapi.databaseservice.WritableDatabaseService.SearchResultPropertiesAdjuster).propertiesAdjuster - the SearchResultPropertiesAdjuster to be removedprotected void _retrieve(AnnotatedPluginDocument[] summaryDocuments, RetrieveCallback callback, URN[] urnsToNotRetrieve) throws DatabaseServiceException
retrieve(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[])
that subclasses should implement.
The default implementation just calls super.retrieve(summaryDocuments, callback, urnsToNotRetrieve).DatabaseServiceExceptionprotected abstract void _retrieve(URN[] urnsToRetrieve, RetrieveCallback callback) throws DatabaseServiceException
retrieve(com.biomatters.geneious.publicapi.documents.URN[], com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback)
that subclasses should implement. Unlike the parent case, implementations of this should
return documents if they exist anywhere within the database folder hierarchy.DatabaseServiceExceptionprotected abstract void _retrieve(Query query, RetrieveCallback callback, URN[] urnsToNotRetrieve) throws DatabaseServiceException
retrieve(com.biomatters.geneious.publicapi.databaseservice.Query, com.biomatters.geneious.publicapi.databaseservice.RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[])
that subclasses should implement.DatabaseServiceExceptionpublic final void retrieve(AnnotatedPluginDocument[] documents, RetrieveCallback callback, URN[] urnsToNotRetrieve) throws DatabaseServiceException
DatabaseServiceSummaryDocuments
then this method must be implemented to allow the full documents to be downloaded.
retrieve in class DatabaseServicedocuments - A list of summary documents.callback - Full documents should be passed on to this callback's add method as they
are being retrieved from the database. It is an error to call any methods
on the callback after retrieve() has returned, or after
callback.setFinalStatus() has been called.urnsToNotRetrieve - a set of document URN's to ignore. Documents matching one of these
URNs must not be passed to the callback, and to save bandwidth,
the DatabaseService should not download them from the database.DatabaseServiceException - if retrieval fails for any reason. May also throw this if the callback requests the retrieve to be cancelled.public final void retrieve(URN[] urnsToRetrieve, RetrieveCallback callback) throws DatabaseServiceException
DatabaseServiceretrieve in class DatabaseServiceurnsToRetrieve - URNs which must be the URNS of documents referenced by a previous document returned from this DatabaseServicecallback - Used to notify when a document has been retrieved.DatabaseServiceException - if retrieval fails for any reason. May also throw this if the callback requests the retrieve to be cancelled.public final void retrieve(Query query, RetrieveCallback callback, URN[] urnsToNotRetrieve) throws DatabaseServiceException
DatabaseServiceretrieve in class DatabaseServicequery - the query specifying what we are searching this DatabaseService for; must not be null.callback - The RetrieveCallback to which to report search results (documents and progress reports); must not be null.urnsToNotRetrieve - a set of document URN's to ignore. retrievers can save bandwidth/disk access by not downloading
documents with the same URN. Must not be null. Most implementations can ignore this method.DatabaseServiceException - if retrieval fails for any reason. May also throw this if the callback requests the retrieve to be cancelled.public boolean isReadOnly()
public abstract int getDocumentCount(boolean includeSubFolders)
includeSubFolders - if true, the returned value should include in the total the number of documents in all sub-folders recursivelypublic static ExtendedSearchOption[] _getExtendedSearchOptions(boolean isAdvancedSearch)
getExtendedSearchOptions(boolean).isAdvancedSearch - whether to get the options for advanced or basic searches as specified in getExtendedSearchOptions(boolean).getExtendedSearchOptions(boolean)public ExtendedSearchOption[] getExtendedSearchOptions(boolean isAdvancedSearch)
_getExtendedSearchOptions(boolean)
Most implementations should not override this, but if they do, they should be aware that collaboration won't provide
this alternative search options.getExtendedSearchOptions in class DatabaseServiceisAdvancedSearch - specifies if the options returned are going be attached to
the advanced or basic search panel. This method will be called twice with true and false.
Disregard this if the extended options are to be on both basic and advanced.public boolean isLocal()
protected abstract WritableDatabaseService _getHiddenFolder(String folderName, boolean isPerUserFolder) throws DatabaseServiceException
getHiddenFolder(String, boolean)folderName - isPerUserFolder - DatabaseServiceExceptionpublic final WritableDatabaseService getHiddenFolder(String folderName, boolean isPerUserFolder) throws DatabaseServiceException
folderName - a unique identifier for this hidden folder.
This must consist of only the following characters: "[a-z][A-Z][0-9] _."isPerUserFolder - If this database has multiple users accessing the same
database simultaneiously and if this parameter is true then the folder
returned is unique for the current user rather than shared.
This is used for example to store agents or collaboration share status
for the current user where each user should have their own independant
data.DatabaseServiceExceptionpublic abstract String[] getHiddenFolderNames() throws DatabaseServiceException
DatabaseServiceExceptionpublic abstract String addHiddenElement(org.jdom.Element newElement, ProgressListener progress) throws DatabaseServiceException
newElement - DatabaseServiceExceptionpublic abstract void addHiddenElement(String name, org.jdom.Element newElement, ProgressListener progress) throws DatabaseServiceException
name - a unique identifier for this element. This must consist of only the following characters: "[a-z][A-Z][0-9] _."newElement - DatabaseServiceExceptionpublic abstract org.jdom.Element getHiddenElement(String elementName, ProgressListener progress) throws DatabaseServiceException
elementName - the value returned from a previous call to addHiddenElement(Element) or the name specified as a parameter to a previous call to addHiddenElement(String, Element) or getHiddenElementNames()DatabaseServiceException - if there is no hidden element with this name or if an I/O error occurs.public abstract String[] getHiddenElementNames() throws DatabaseServiceException
DatabaseServiceExceptionpublic abstract void updateHiddenElement(String name, org.jdom.Element newElement, ProgressListener progress) throws DatabaseServiceException
name - the name returned from a previous call to addHiddenElement(Element) or the name specified as a parameter to a previous call to addHiddenElement(String, Element)newElement - the new element to be saved.DatabaseServiceExceptionpublic abstract void removeHiddenElement(String name) throws DatabaseServiceException
name - the name returned from a previous call to addHiddenElement(Element) or the name specified as a parameter to a previous call to addHiddenElement(String, Element). If a hidden element with this name doesn't exist, this method does nothing,DatabaseServiceExceptionpublic WritableDatabaseService createFolderViewFolder(String folderName, AnnotatedPluginDocument folderViewDocument) throws DatabaseServiceException
getFolderViewDocument().
The database implementation is responsible for updating the folderViewDocument to record changes made
using addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener) which must include calling
FolderView.addDocumentProperties(com.biomatters.geneious.publicapi.documents.URN, java.util.Map)
for every document, even if they don't have properties.folderName - the new name for the folder. If there is already a folder with this name, this method throws a DatabaseServiceException.folderViewDocument - the document to be displayed when this folder is selected.DatabaseServiceException - if a folder named this already exists or if the folder cannot be created.public void setFolderViewDocument(AnnotatedPluginDocument folderViewDocument, ProgressListener progressListener) throws DatabaseServiceException
createFolderViewFolder(String, com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument)
for more information on folder view documents. Passing in null removes the folder view from the folder and deletes the folder view document if nothing else references it.
This method doesn't save the folder view document if it already exists in the database. Call AnnotatedPluginDocument.saveDocument()
first in this case.folderViewDocument - the new folder view document for this folder or null to remove any folder view document.progressListener - progress listener for recording progress and handling cancel.DatabaseServiceException - if the document cannot be saved.public final AnnotatedPluginDocument getFolderViewDocument() throws DatabaseServiceException
_getFolderViewDocument()DatabaseServiceException_getFolderViewDocument()protected AnnotatedPluginDocument _getFolderViewDocument() throws DatabaseServiceException
getFolderViewDocument(). Services should override this method to provide their folder view document.DatabaseServiceExceptionpublic final AnnotatedPluginDocument addDocumentCopyWithProperties(AnnotatedPluginDocument document, ProgressListener progress, Map<String,Object> properties) throws DatabaseServiceException
DatabaseServiceExceptionpublic final AnnotatedPluginDocument addDocumentCopyWithProperties(AnnotatedPluginDocument document, ProgressListener progress, Map<String,Object> properties, URN urnToUseForAddedDocument) throws DatabaseServiceException
createFolderViewFolder(String,AnnotatedPluginDocument). The implementation of addDocumentCopyWithProperties
is responsible for recording these properties in the FolderViewDocument.
See addDocumentCopy(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener) for
other information about adding documents to databases.document - the document to add a copy ofprogress - reports progressproperties - properties for the docuemnt. May be null.urnToUseForAddedDocument - the urn to use for the newly added copy. This may be null, in which case a URN will be generated. If this is not null, it must be a URN returned from a previous call to createUrnForDocumentSoonToBeAdded()DatabaseServiceException - if the document fails to be added.protected AnnotatedPluginDocument _addDocumentCopyWithProperties(AnnotatedPluginDocument document, ProgressListener progress, Map<String,Object> properties) throws DatabaseServiceException
DatabaseServiceExceptionprotected AnnotatedPluginDocument _addDocumentCopyWithProperties(AnnotatedPluginDocument document, ProgressListener progress, Map<String,Object> properties, URN urnToUseForAddedDocument) throws DatabaseServiceException
addDocumentCopyWithProperties(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, jebl.util.ProgressListener, java.util.Map, com.biomatters.geneious.publicapi.documents.URN).
Subclasses implement this instead of addDocumentCopyWithProperties.DatabaseServiceExceptionpublic void waitForSearchIndexingToComplete()
public Object getLock()
thispublic Color getColor(boolean loadNow)
loadNow - true to force load the color from disk now. False to use the in memory cache. Usually this parameter should be false unless some external code has manually copied hiddenFolder elements (which store the color) from elsewhere.public void setColor(Color newColor)
newColor - the new text color for this folder or null to use the default colorprotected void initialize(GeneiousServiceListener listener)
GeneiousServiceWritableDatabaseService this method is called first thing after creating the service using a parameterless constructor.
If this is a WritableDatabaseService, methods that deal
with hidden folders and hidden elements may be called before initialize. These include getHiddenElementNames(),
getHiddenFolder(String, boolean) and
getHiddenElement(String, jebl.util.ProgressListener).
External classes should not call this method. They should instead use GeneiousService.initializeService(GeneiousServiceListener)
which sets up internal handlers and calls this method. Even then, generally only the Geneious application itself should be
calling GeneiousService.initializeService(GeneiousServiceListener).initialize in class GeneiousServicelistener - a listener for reporting changes to the service, such as status changes or new child services.