Package org.intermine.client.services

Class TemplateService

  • public class TemplateService
extends AbstractQueryService<org.intermine.template.TemplateQuery>

    The TemplateService represents the connection to the resource that returns results of templates and number of results.

    A template is a predefined query, with a set number of configurable parameters, similar to a search form. Only a subset of their actual constraints are editable, although at least one will be. For example you might have a template that finds Alcohol-Dehydrogenase genes in a specific organism - although this would require a couple of constraints, only the one that specifies the organism need be visible to the end user.

    From the user's perspective, templates can offer two advantages:

    • They can be simpler to run, as only the parts of the query relevant to the particular search need to be specified (for example you never need to set the output columns)
    • They provide simple access to a saved query from anywhere the webservice is available - so while queries can be saved as XML on your own machine, as a template they can be run from anywhere

    There are two ways to use templates - either you can fetch a template object from the service, and use that to build the request, or you can build it by referencing the parameters and output. The former method is preferable as it will catch errors caused by changes to the template structure earlier on, and allow you to introspect the template.

    Using a Template object:

     PrintStream out = System.out;

 ServiceFactory serviceFactory = new ServiceFactory(serviceRootUrl);
 TemplateService templateService = serviceFactory.getTemplateService();

 // Refer to the template by its name (displayed in the browser's address bar)
 String templateName = "ChromLocation_GeneTranscriptExon";
 TemplateQuery template = templateService.getTemplate(templateName);

 // You only need to specify the values of the constraints you wish to alter:
 template.replaceConstraint(template.getConstraintForCode("B"),
 Constraints.eq("Chromosome.primaryIdentifier", "2L"));

 Iterator> resultSet = templateService.getRowListIterator(template, new Page(0, 10));

 out.println(StringUtils.join(template.getView(), "\t"));
 while (resultSet.hasNext()) {
     out.println(StringUtils.join(resultSet.next(), "\t"));
 }

    When using the other method, it is assumed that if you are familiar with the template's parameters and output. Using the name and parameter method saves a call to the service to retrieve the template in the first place:

    Using template name and parameters:

     PrintStream out = System.out;

 ServiceFactory serviceFactory = new ServiceFactory(serviceRootUrl);
 TemplateService templateService = serviceFactory.getTemplateService();

 // Refer to the template by its name (displayed in the browser's address bar)
 String templateName = "ChromLocation_GeneTranscriptExon";

 // Specify the values for this particular request
 List parameters = new ArrayList();
 parameters.add(new TemplateParameter("Chromosome.organism.name", "eq", "*melanogaster"));
 parameters.add(new TemplateParameter("Chromosome.primaryIdentifier", "eq", "2L"));
 parameters.add(new TemplateParameter("Chromosome.locatedFeatures.start", "ge", "1"));
 parameters.add(new TemplateParameter("Chromosome.locatedFeatures.end", "lt", "10000"));

 Iterator> resultSet = templateService.getRowListIterator(templateName, parameters,
                                       new Page(0, 10));

 while (resultSet.hasNext()) {
     out.println(StringUtils.join(resultSet.next(), "\t"));
 }

    • Constructor Detail

      • TemplateService

        public TemplateService​(java.lang.String rootUrl,
                       java.lang.String applicationName)
        Use ServiceFactory instead of constructor for creating this service.
        Parameters:
        rootUrl - root URL
        applicationName - application name

    • Method Detail

      • getTemplateNames

        public java.util.Set<java.lang.String> getTemplateNames()
        Get the names of the templates to which the current user has access.
        Returns:
        The names of the available templates.

      • getTemplates

        public java.util.Map<java.lang.String,​org.intermine.template.TemplateQuery> getTemplates()
        Get the templates to which the current user has access.
        Returns:
        The templates the user can access.

      • getTemplate

        public org.intermine.template.TemplateQuery getTemplate​(java.lang.String name)
        Get the template with the given name, if accessible. Returns null if the template does not exist or the current user cannot access it.
        Parameters:
        name - The name of the template to return.
        Returns:
        The template with the given name.

      • getTemplatesForType

        public java.util.Set<org.intermine.template.TemplateQuery> getTemplatesForType​(java.lang.String type)
        Get all the templates with constraints which constrain paths of a certain type. If a template has a constraint on "Employee.name", then that template will be included in the set of results for when type is "Employee", as well as when type is "Manager".
        Parameters:
        type - The type of object to enquire about.
        Returns:
        The set of suitable templates.

      • getCount

        public int getCount​(java.lang.String templateName,
                    java.util.List<TemplateParameter> parameters)
        Returns the number of results the specified template will return.
        Parameters:
        templateName - the name of the template to run
        parameters - the values for the templates editable constraints
        Returns:
        number of results of specified query.

      • getCount

        public int getCount​(org.intermine.template.TemplateQuery template)

      • getAllResults

        public java.util.List<java.util.List<java.lang.String>> getAllResults​(java.lang.String templateName,
                                                                      java.util.List<TemplateParameter> parameters)
        Returns all the results for the given template template with the given parameters. If you expect a lot of results we would recommend you use getAllResultIterator() method.
        Parameters:
        templateName - template name
        parameters - parameters of template
        Returns:
        results

      • getResults

        public java.util.List<java.util.List<java.lang.String>> getResults​(java.lang.String templateName,
                                                                   java.util.List<TemplateParameter> parameters,
                                                                   Page page)
        Returns a set of the results for the given template template with the given parameters, defined by the index of the first result you want back, and the maximum page size. If you expect a lot of results we would recommend you use getResultIterator() method.
        Parameters:
        templateName - template name
        parameters - parameters of template
        page - The subsection of the result set to retrieve.
        Returns:
        A result set starting at the given index and no larger than the maximum page size.

      • getResults

        public java.util.List<java.util.List<java.lang.String>> getResults​(org.intermine.template.TemplateQuery template,
                                                                   Page page)

      • getAllJSONResults

        public java.util.List<org.json.JSONObject> getAllJSONResults​(java.lang.String templateName,
                                                             java.util.List<TemplateParameter> parameters)
                                                      throws org.json.JSONException
        Returns all the results for the given template template with the given parameters, as JSON objects (see @link {http://www.intermine.org/wiki/JSONObjectFormat}).
        Parameters:
        templateName - template name
        parameters - parameters of template
        Returns:
        results
        Throws:
        org.json.JSONException - if the server returns content that cannot be parsed as JSON

      • getJSONResults

        public java.util.List<org.json.JSONObject> getJSONResults​(java.lang.String templateName,
                                                          java.util.List<TemplateParameter> parameters,
                                                          Page page)
                                                   throws org.json.JSONException
        Returns a subset of the results for the given template template with the given parameters, as JSON objects (see @link {http://www.intermine.org/wiki/JSONObjectFormat}).
        Parameters:
        templateName - template name
        parameters - parameters of template
        page - The subsection of the result set to retrieve.
        Returns:
        a list of JSON objects
        Throws:
        org.json.JSONException - if the server returns content that cannot be parsed as JSON

      • getJSONResults

        public java.util.List<org.json.JSONObject> getJSONResults​(org.intermine.template.TemplateQuery template,
                                                          Page page)
                                                   throws org.json.JSONException
        Throws:
        org.json.JSONException

      • getAllRowsIterator

        public java.util.Iterator<java.util.List<java.lang.String>> getAllRowsIterator​(java.lang.String templateName,
                                                                               java.util.List<TemplateParameter> parameters)
        Returns all the rows for the template when run with the given parameters. Use this method if you expect a lot of results and you would otherwise run out of memory.
        Parameters:
        templateName - template name
        parameters - parameters of template
        Returns:
        results as an iterator over lists of strings

      • getRowIterator

        public java.util.Iterator<java.util.List<java.lang.String>> getRowIterator​(java.lang.String templateName,
                                                                           java.util.List<TemplateParameter> parameters,
                                                                           Page page)
        Returns an iterator over a subset of rows for the template when run with the given parameters. Use this method if you expect a lot of results and you would otherwise run out of memory.
        Parameters:
        templateName - template name
        parameters - parameters of template
        page - The subsection of the result set to retrieve.
        Returns:
        results as an iterator over lists of strings

      • getRowIterator

        public java.util.Iterator<java.util.List<java.lang.String>> getRowIterator​(org.intermine.template.TemplateQuery template,
                                                                           Page page)

      • getRowsAsLists

        public java.util.List<java.util.List<java.lang.Object>> getRowsAsLists​(java.lang.String name,
                                                                       java.util.List<TemplateParameter> params,
                                                                       Page page)
        Get results for a query as rows of objects.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        page - The subsection of the result set to retrieve.
        Returns:
        a list of rows, which are each a list of cells.

      • getRowsAsLists

        public java.util.List<java.util.List<java.lang.Object>> getRowsAsLists​(java.lang.String name,
                                                                       java.util.List<TemplateParameter> params)
        Get results for a query as rows of objects. Retrieve up to 10,000,000 rows from the beginning.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        Returns:
        a list of rows, which are each a list of cells.

      • getRowsAsMaps

        public java.util.List<java.util.Map<java.lang.String,​java.lang.Object>> getRowsAsMaps​(java.lang.String name,
                                                                                            java.util.List<TemplateParameter> params,
                                                                                            Page page)
        Get results for a query as rows of objects.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        page - The subsection of the result set to retrieve.
        Returns:
        a list of rows, which are each a map from output column (in alternate long and short form) to value.

      • getRowsAsMaps

        public java.util.List<java.util.Map<java.lang.String,​java.lang.Object>> getRowsAsMaps​(java.lang.String name,
                                                                                            java.util.List<TemplateParameter> params)
        Get results for a query as rows of objects. Get up to the maximum result size of 10,000,000 rows from the beginning.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        Returns:
        a list of rows, which are each a map from output column (in alternate long and short form) to value.

      • getRowListIterator

        public java.util.Iterator<java.util.List<java.lang.Object>> getRowListIterator​(java.lang.String name,
                                                                               java.util.List<TemplateParameter> params,
                                                                               Page page)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        page - The subsection of the result set to retrieve.
        Returns:
        an iterator over the rows, where each row is a list of objects.

      • getRowListIterator

        public java.util.Iterator<java.util.List<java.lang.Object>> getRowListIterator​(java.lang.String name,
                                                                               java.util.List<TemplateParameter> params)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection. Retrieves up to the maximum result size of 10,000,000 rows from the beginning.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        Returns:
        an iterator over the rows, where each row is a list of objects.

      • getRowMapIterator

        public java.util.Iterator<java.util.Map<java.lang.String,​java.lang.Object>> getRowMapIterator​(java.lang.String name,
                                                                                                    java.util.List<TemplateParameter> params,
                                                                                                    Page page)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        page - The subsection of the result set to retrieve.
        Returns:
        an iterator over the rows, where each row is a mapping from output column to value.

      • getRowMapIterator

        public java.util.Iterator<java.util.Map<java.lang.String,​java.lang.Object>> getRowMapIterator​(java.lang.String name,
                                                                                                    java.util.List<TemplateParameter> params)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection, up to the maximum result size of 10,000,000 rows from the beginning.
        Parameters:
        name - The name of the template to run.
        params - The settings for the various template constraints.
        Returns:
        an iterator over the rows, where each row is a mapping from output column to value.

      • getRows

        protected RowResultSet getRows​(org.intermine.template.TemplateQuery query,
                               Page page)