public abstract class GeneiousService extends Object
DatabaseService and friends), but other types
of services are possible, even though the public API has not finalized details on all of them.
All methods below that return lists are allowed to return an empty list (e.g. Collections.emptyList())
but not null.
A plugin may provide a set of services via GeneiousPlugin.getServices().
The following is an example of a GeneiousService as an anonymous inner class:
new GeneiousService[]{
new DatabaseService(){
public String getUniqueID() {
return "SampleService";
}
public String getName() {
return "Empty Service";
}
public String getDescription() {
return "An empty service";
}
public String getHelp() {
return "Help with the service!";
}
public Icons getIcons() {
return null;
}
public QueryField[] getSearchFields() {
return new QueryField[]{
new QueryField(new DocumentField("Name","The sequence name","name",String.class,false,false),new Condition[]{Condition.CONTAINS}),
new QueryField(new DocumentField("Residues","The sequence residues","residues",String.class,false,false),new Condition[]{Condition.CONTAINS})
};
}
File fasta = new File(pluginDir.getAbsolutePath()+File.separator+"sampledb.fasta");
//we find results based on the given query, and return them using the callback supplied.
public void retrieve(Query query, RetrieveCallback callback, URN[] urnsToNotRetrieve) throws DatabaseServiceException {
//some basic error handling
if(!fasta.exists()) {
throw new DatabaseServiceException("Fasta file does not exist (file name="+fasta+")",false);
}
try{
BufferedReader in = new BufferedReader(new FileReader(fasta));
String currentLine = "";
String name = "";
String residues = "";
ArrayList nameToMatch = new ArrayList();
ArrayList residuesToMatch = new ArrayList();
boolean matchEverything = false; //this is true if we want both the name and the residues to match for a document to be included in the seaarch results
//we will store a list of the queries
java.util.List queries;
//a compoundSearchQuery consists of a number of queries
//we'll put them in the list
if(query instanceof CompoundSearchQuery){
CompoundSearchQuery cQuery = (CompoundSearchQuery)query;
matchEverything = cQuery.getOperator() == CompoundSearchQuery.Operator.AND;
queries = (java.util.List) cQuery.getChildren();
}
//if the query is not a CompoundSearchQuery, then we can create a one-element list containing the query
else {
queries = new ArrayList();
queries.add(query);
}
//we'll loop through all the queries, and set the nameToMatch and residuesToMatch
for(Query q : queries){
//we have the sequence and name, do the searching
if(q instanceof AdvancedSearchQueryTerm){
AdvancedSearchQueryTerm advancedQuery = (AdvancedSearchQueryTerm)q;
if(advancedQuery.getField().getCode().equals("name")){
nameToMatch.add(advancedQuery.getValues()[0].toString().toUpperCase());
}
else if(advancedQuery.getField().getCode().equals("residues")){
residuesToMatch.add(advancedQuery.getValues()[0].toString().toUpperCase());
}
}
//a BasicSearchQuery consists of one field (search text)
//you can extend a basic query, for example using a CompoundSearchQuery
else if (q instanceof BasicSearchQuery) {
//set both the name and the residue searches to the query entered
BasicSearchQuery bq = (BasicSearchQuery)query;
nameToMatch.add(bq.getSearchText().toUpperCase());
residuesToMatch.add(bq.getSearchText().toUpperCase());
}
else{
//do nothing
}
}
//if neither nameToMatch or residuesToMatch are set at this point, the search will return no results.
//now lets loop through the fasta file
while((currentLine = in.readLine()) != null){
//fasta files consist of 'name' lines (denoted by a beginning '>' character), and then a number of 'residue' lines
if(currentLine.startsWith(">")){
if(!name.equals("")){
//we get to this part of the code once we have read in one sequence (a name line and the residue lines)
//so we must now do a match on the name and residues that we have read in
SequenceDocument doc = match(nameToMatch,name,residuesToMatch,residues, matchEverything);
if(doc != null){
//add a search result if there is one
callback.add(doc, Collections.emptyMap());
}
}
//set the name variable to the new sequence name, and reset the residues variable
name = currentLine.substring(1,currentLine.length());
residues = "";
}
else{
//keep concatenating the residues as we move through the fasta file
residues += currentLine;
}
}
//we need to do the match one last time once we reach the end of the file
SequenceDocument doc = match(nameToMatch,name,residuesToMatch,residues, matchEverything);
if(doc != null){
callback.add(doc, Collections.emptyMap());
}
}
catch(IOException e){
//pass on any exceptions we get reading the file
throw new DatabaseServiceException(e,e.getMessage(),false);
}
}
//this utility method returns a SequenceDocument based on the given name and residues, if they match the search parameters
//or null if there is no match
private SequenceDocument match(ArrayList namesToMatch, String name, ArrayList residuesToMatch, String residues, boolean matchBoth){
boolean nameMatch = namesToMatch.size() == 0;
boolean residueMatch = residuesToMatch.size() == 0;
if(namesToMatch.size() > 0){
nameMatch = matchBoth;
for(String nameToMatch : namesToMatch){
if(name.toUpperCase().contains(nameToMatch) == !matchBoth){
nameMatch = !matchBoth;
}
}
}
if(residuesToMatch.size() > 0){
residueMatch = matchBoth;
for(String residueToMatch : residuesToMatch){
if(residues.toUpperCase().contains(residueToMatch) == !matchBoth){
residueMatch = !matchBoth;
}
}
}
if(residueMatch && nameMatch){
return new DefaultNucleotideSequence(name.substring(0,name.indexOf(" ")),name,residues,new Date(fasta.lastModified()));
}
return null;
}
}
};
| Modifier and Type | Class and Description |
|---|---|
static class |
GeneiousService.ServiceStatus
Possible states of service.
|
| Constructor and Description |
|---|
GeneiousService() |
| Modifier and Type | Method and Description |
|---|---|
protected void |
_shutdown()
The implementation method for
shutdown(). |
void |
addGeneiousServiceListener(GeneiousServiceListener listener)
Add a listener to be notified about changes to this service.
|
void |
addWeakGeneiousServiceListener(GeneiousServiceListener listener)
Add a weakly referenced listener to be notified about changes to this service.
|
boolean |
canShutdown()
This is called to check whether the system can close.
|
List<GeneiousAction> |
getActionsAlwaysEnabled()
a list of Geneious Actions which can appear in the menu bar, toolbar or popup-menu in the service tree.
|
List<GeneiousAction> |
getActionsEnabledWhenServiceSelected()
List of Geneious Actions which can appear in the menu bar, toolbar or popup-menu in the service tree.
|
List<GeneiousService> |
getChildServices()
Provides a list of all the current children of this service.
|
abstract String |
getDescription()
This gives the human-readable short description of the service as it might appear in
any user-interface.
|
String |
getFullPath()
Gives you the full path to this service as it appears in the Geneious service tree.
|
protected GeneiousServiceListener |
getGeneiousServiceListener()
Get the service passed to the
initialize(GeneiousServiceListener) method. |
abstract String |
getHelp()
Help text.
|
abstract Icons |
getIcons()
Icons used in the service list.
|
abstract String |
getName()
This gives the human-readable name of the service as it might appear in
any user-interface.
|
GeneiousService |
getParentService()
Get the parent service of this service or null if this service has no parent (it is the root service).
|
GeneiousPreferences |
getPreferences()
Deprecated.
use
GeneiousPlugin.getPluginPreferences() instead |
String |
getServiceTreeLabel(boolean expanded,
boolean showAdditionalInformation)
Provide additional details for a human user.
|
GeneiousService.ServiceStatus |
getStatus(boolean returnUnavailableIfLicensePreventsUsage)
Gets the status of this service.
|
abstract String |
getUniqueID()
Get a unique identifier for this GeneiousService.
|
boolean |
hasShutdownOrStartedShuttingDown()
Returns true if this service or its parent service has been
shutdown() or if it is in the process of shutting down. |
protected void |
initialize(GeneiousServiceListener listener)
Constructor method - initializes the service.
|
void |
initializeService(GeneiousServiceListener listener)
Initializes this service by setting up internal handlers and delegating to
initialize(GeneiousServiceListener). |
boolean |
isProOnly()
This function returns true if the service requires an active license.
|
void |
removeGeneiousServiceListener(GeneiousServiceListener listener)
Remove a listener to be notified about changes to this service.
|
boolean |
showInServiceTree()
Override and return false to hide this service from the service tree.
|
void |
shutdown()
This method is called Geneious is shutting down or the plugin that provided this service is being disabled.
|
String |
toString() |
public abstract String getUniqueID()
PluginUtilities.getGeneiousService(String) String)}
can be used to find this GeneiousService and so that agents can find the service each time Geneious is run.
Hence the unique id for a service should never change. It cannot be null.
A unique identifier may consist of any valid Java identifier characters (see Character.isJavaIdentifierPart(char) as well as the space character.
Warning: Changing the unique ID may imply breaking backward compatibility with existing documents
in the local database.
If in doubt, using Object.getClass().getName() is a reasonable unique ID as long as the class name does not change.public abstract String getName()
public String getServiceTreeLabel(boolean expanded, boolean showAdditionalInformation)
showAdditionalInformation - if true, then optionally add extra information,
such as the number of documents contained within the serviceexpanded - if the service's children are visible in the tree.public abstract String getDescription()
public final String getFullPath()
getServiceTreeLabel(true,false)
(or getName() if getServiceTreeLabel returns null) of all the ancestor services
(excluding the root service) and this service together with '/' separators.public abstract String getHelp()
public abstract Icons getIcons()
public List<GeneiousAction> getActionsAlwaysEnabled()
getActionsEnabledWhenServiceSelected().
If an action has been setEnabled(false) (non-default) then the action will always be disabled in Geneious.public List<GeneiousAction> getActionsEnabledWhenServiceSelected()
protected void initialize(GeneiousServiceListener listener)
WritableDatabaseService 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 WritableDatabaseService.getHiddenElementNames(),
WritableDatabaseService.getHiddenFolder(String, boolean) and
WritableDatabaseService.getHiddenElement(String, jebl.util.ProgressListener).
External classes should not call this method. They should instead use initializeService(GeneiousServiceListener)
which sets up internal handlers and calls this method. Even then, generally only the Geneious application itself should be
calling initializeService(GeneiousServiceListener).listener - a listener for reporting changes to the service, such as status changes or new child services.public GeneiousService.ServiceStatus getStatus(boolean returnUnavailableIfLicensePreventsUsage)
GeneiousService.ServiceStatus.UNAVAILABLE
while it hasn't been initialized, and GeneiousService.ServiceStatus.AVAILABLE once it has finished initializing (by returning
from initializeService(GeneiousServiceListener)) GeneiousService.ServiceStatus.AVAILABLE.returnUnavailableIfLicensePreventsUsage - true to return GeneiousService.ServiceStatus.UNAVAILABLE no matter what the real status of this service is if it is a restricted service and the user doesn't have an active license.addGeneiousServiceListener(GeneiousServiceListener),
GeneiousServiceListener.statusChanged(com.biomatters.geneious.publicapi.plugin.GeneiousService.ServiceStatus)public final void initializeService(GeneiousServiceListener listener)
initialize(GeneiousServiceListener).
Generally only the Geneious application itself should be
calling this method.listener - a listener for reporting changes to the service, such as status changes or new child services.protected GeneiousServiceListener getGeneiousServiceListener()
initialize(GeneiousServiceListener) method.
This method exists primarily so super/sub-classes have access to the listenerinitialize(GeneiousServiceListener) method.public final List<GeneiousService> getChildServices()
addGeneiousServiceListener(GeneiousServiceListener)
public final GeneiousService getParentService()
GeneiousServiceListener.childServiceAdded(GeneiousService)
or if it has been removed from its parent service
(using GeneiousServiceListener.childServiceRemoved(GeneiousService)public final void addGeneiousServiceListener(GeneiousServiceListener listener)
listener - the listener to be notified.public final void addWeakGeneiousServiceListener(GeneiousServiceListener listener)
listener - the listener to be notified.public final void removeGeneiousServiceListener(GeneiousServiceListener listener)
listener - the listener previously added using addGeneiousServiceListener(GeneiousServiceListener)public boolean canShutdown()
public final void shutdown()
canShutdown().
This method delegates to the implementation method _shutdown().
This method will not return until the shutdown has completed.
This method may be called from multiple threads, in which case only
a single call is made to _shutdown() and no calls
to this method will return until the call to _shutdown()
has completed.protected void _shutdown()
shutdown(). Any subclass
that wants to take special action when shutdown is called should
override this method.shutdown(),
hasShutdownOrStartedShuttingDown()public final boolean hasShutdownOrStartedShuttingDown()
shutdown() or if it is in the process of shutting down.shutdown()public GeneiousPreferences getPreferences()
GeneiousPlugin.getPluginPreferences() insteadpublic boolean isProOnly()
public boolean showInServiceTree()
GeneiousServiceListener.serviceTreeLabelChanged()