gov.nih.nci.caarray.services.external.v1_0.search
Interface SearchService


public interface SearchService

Remote service for search and data enumeration. Used by the grid service, and can also be used directly by EJB clients. Several methods in this service accept a LimitOffset parameter to allow the client to request a subset of the results that would otherwise be matched by the provided criteria. For these methods, there may also be a maximum number of results that the system is willing to return for that query, regardless of the limit requested by the client. This maximum is not specified in the method definition (and varies between the methods), but will be be indicated in the return value. The actual number of results returned for these methods will then be the smaller of { maximum system threshold, limit requested by client in the LimitOffset parameter, actual number of results available (taking into account the offset specified)

Author:
dkokotov

Field Summary
static java.lang.String JNDI_NAME
          The JNDI name to look up this Remote EJB under.
 
Method Summary
 java.util.List<Category> getAllCharacteristicCategories(CaArrayEntityReference experimentRef)
          Retrieve the list of all categories of characteristics, either in the entire system, or for given experiment.
 java.util.List<Person> getAllPrincipalInvestigators()
          Retrieve list of Person entities that are Principal Investigators on at least one experiment in the system.
 AnnotationSet getAnnotationSet(AnnotationSetRequest request)
          Returns an annotation set matching the given request.
 java.util.List<Term> getTermsForCategory(CaArrayEntityReference categoryRef, java.lang.String valuePrefix)
          Retrieve the list of all terms belonging to given category in the system.
<T extends AbstractCaArrayEntity>
SearchResult<T>
searchByExample(ExampleSearchCriteria<T> criteria, LimitOffset limitOffset)
          Search for entities based on a specified example.
 SearchResult<Biomaterial> searchForBiomaterials(BiomaterialSearchCriteria criteria, LimitOffset limitOffset)
          Search for biomaterials satisfying the given search criteria.
 SearchResult<Biomaterial> searchForBiomaterialsByKeyword(BiomaterialKeywordSearchCriteria criteria, LimitOffset limitOffset)
          Search for biomaterials matching the given keyword criteria.
 SearchResult<Experiment> searchForExperiments(ExperimentSearchCriteria criteria, LimitOffset limitOffset)
          Search for experiments satisfying the given search criteria.
 SearchResult<Experiment> searchForExperimentsByKeyword(KeywordSearchCriteria criteria, LimitOffset limitOffset)
          Search for experiments matching the given keyword keyword criteria.
 SearchResult<File> searchForFiles(FileSearchCriteria criteria, LimitOffset limitOffset)
          Search for files satisfying the given search criteria.
 SearchResult<Hybridization> searchForHybridizations(HybridizationSearchCriteria criteria, LimitOffset limitOffset)
          Search for hybridizations satisfying the given search criteria.
 java.util.List<QuantitationType> searchForQuantitationTypes(QuantitationTypeSearchCriteria criteria)
          Returns a list of quantitation types satisfying the given search criteria.
 

Field Detail

JNDI_NAME

static final java.lang.String JNDI_NAME
The JNDI name to look up this Remote EJB under.

See Also:
Constant Field Values
Method Detail

getAllPrincipalInvestigators

java.util.List<Person> getAllPrincipalInvestigators()
Retrieve list of Person entities that are Principal Investigators on at least one experiment in the system. A Person is considered a Principal Investigator if he/she is an experiment contact on an experiment with a set of roles that includes the "investigator" term from the MGED ontology.

Returns:
the list of Person entities that are principal investigators on at least one experiment in the system.

getAllCharacteristicCategories

java.util.List<Category> getAllCharacteristicCategories(CaArrayEntityReference experimentRef)
                                                        throws InvalidReferenceException
Retrieve the list of all categories of characteristics, either in the entire system, or for given experiment. This list always includes the following "standard" categories: In addition if an experiment specified, then it includes all categories from any characteristics belonging to any of the biomaterials in that experiment. If an experiment is not specified, then it includes all categories from any characteristics belonging to any of the biomaterials in the entire system.

Parameters:
experimentRef - if not null, then only categories of characteristics of biomaterials in the given experiment are returned, otherwise categories of all characteristics in the system are returned.
Returns:
the list of Category entities as described above.
Throws:
InvalidReferenceException - if the given reference does not identify an existing experiment in the system.

getTermsForCategory

java.util.List<Term> getTermsForCategory(CaArrayEntityReference categoryRef,
                                         java.lang.String valuePrefix)
                                         throws InvalidReferenceException
Retrieve the list of all terms belonging to given category in the system.

Parameters:
categoryRef - reference identifying the category
valuePrefix - if not null, only include terms whose value starts with given prefix, using case insensitive matching
Returns:
the terms in the given category, possibly filtered for the given prefix
Throws:
InvalidReferenceException - if the given reference does not identify an existing category in the system.

searchForExperiments

SearchResult<Experiment> searchForExperiments(ExperimentSearchCriteria criteria,
                                              LimitOffset limitOffset)
                                              throws InvalidReferenceException,
                                                     UnsupportedCategoryException
Search for experiments satisfying the given search criteria.

Parameters:
criteria - the search criteria.
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching experiments and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.
Throws:
InvalidReferenceException - if any references within the given criteria are not valid, e.g. refer to entities that do not exist or are not of the correct types
UnsupportedCategoryException - if the search criteria includes an annotation criterion with a category other that disease state, cell type, material type, tissue site.

searchForExperimentsByKeyword

SearchResult<Experiment> searchForExperimentsByKeyword(KeywordSearchCriteria criteria,
                                                       LimitOffset limitOffset)
Search for experiments matching the given keyword keyword criteria. The following fields are used to match the keyword

Parameters:
criteria - the keyword criteria to search for.
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching experiments and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.

searchForBiomaterials

SearchResult<Biomaterial> searchForBiomaterials(BiomaterialSearchCriteria criteria,
                                                LimitOffset limitOffset)
                                                throws InvalidReferenceException,
                                                       UnsupportedCategoryException
Search for biomaterials satisfying the given search criteria.

Parameters:
criteria - the search criteria
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching biomaterials and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.
Throws:
InvalidReferenceException - if any references within the given criteria are not valid, e.g. refer to entities that do not exist or are not of the correct types
UnsupportedCategoryException - if the search criteria includes an annotation criterion with a category other that disease state, cell type, material type, tissue site.

searchForBiomaterialsByKeyword

SearchResult<Biomaterial> searchForBiomaterialsByKeyword(BiomaterialKeywordSearchCriteria criteria,
                                                         LimitOffset limitOffset)
Search for biomaterials matching the given keyword criteria. The following fields are used to match the keyword

Parameters:
criteria - the keyword criteria to search for; this identifies the string to look for, and the types of biomaterials to include in the results.
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching biomaterials and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.

searchForHybridizations

SearchResult<Hybridization> searchForHybridizations(HybridizationSearchCriteria criteria,
                                                    LimitOffset limitOffset)
                                                    throws InvalidReferenceException
Search for hybridizations satisfying the given search criteria.

Parameters:
criteria - the search criteria
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching hybridizations and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.
Throws:
InvalidReferenceException - if any references within the given criteria are not valid, e.g. refer to entities that do not exist or are not of the correct types

searchForFiles

SearchResult<File> searchForFiles(FileSearchCriteria criteria,
                                  LimitOffset limitOffset)
                                  throws InvalidReferenceException
Search for files satisfying the given search criteria. Note that the File instances returned by this search only contain file metadata; to retrieve the actual file contents, use the file retrieval methods in DataService.

Parameters:
criteria - the search criteria.
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching hybridizations and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.
Throws:
InvalidReferenceException - if any references within the given criteria are not valid, e.g. refer to entities that do not exist or are not of the correct types
See Also:
DataService

searchForQuantitationTypes

java.util.List<QuantitationType> searchForQuantitationTypes(QuantitationTypeSearchCriteria criteria)
                                                            throws InvalidReferenceException,
                                                                   InvalidInputException
Returns a list of quantitation types satisfying the given search criteria.

Parameters:
criteria - the search criteria. The criteria must, at a minimum, include a reference to a Hybridization.
Returns:
the list of QuantitationType matching criteria.
Throws:
InvalidReferenceException - if any references within the given criteria are not valid, e.g. refer to entities that do not exist or are not of the correct types
InvalidInputException - if the search criteria does not have a non-null Hybridization reference

searchByExample

<T extends AbstractCaArrayEntity> SearchResult<T> searchByExample(ExampleSearchCriteria<T> criteria,
                                                                  LimitOffset limitOffset)
                                                              throws InvalidInputException
Search for entities based on a specified example. Searches by example use the root example entities, as well as its directly associated entities, to construct the query. Entities with association chains of more than 1 link to the root example entities are ignored. The ExampleSearchCriteria class also allows the caller to specify how to treat empty and zero-valued properties, and how string comparisons should be done.

Type Parameters:
T - type of the example entity
Parameters:
criteria - the criteria specifying the example entity, as well as rules defining how candidate entities are matched against the example
limitOffset - an optional parameter specifying the number of results to return, and the offset of the first result to return within the overall result set. May be left null to indicate the entire result set is requested.
Returns:
a SearchResult with the matching entities and metadata on the subset of matching results actually returned. This may be smaller than the requested number of results - see the class level Javadoc for details.
Throws:
InvalidInputException - if a null example is given

getAnnotationSet

AnnotationSet getAnnotationSet(AnnotationSetRequest request)
                               throws InvalidReferenceException
Returns an annotation set matching the given request. This annotation set consists of the values of Characteristics with categories specified in the request across the experiment nodes (biomaterials and/or hybridizations) specified in the request.

The annotation set will include an AnnotationColumn for each ExperimentGraphNode included in the request; each AnnotationColumn will include an AnnotationValueSet for each Category included in the request. The AnnotationValueSet for a given experiment node and characteristic category is calculated as follows:

Parameters:
request - the annotation set request
Returns:
the annotation set.
Throws:
InvalidReferenceException - if any references within the given criteria are not valid, e.g. refer to entities that do not exist or are not of the correct types