Package org.intermine.webservice.server

Class WebService

  • Direct Known Subclasses:
    AbstractQueryService, AvailableListsService, AvailableTemplatesService, DeregistrationService, JaccardIndexService, JSONService, ModelService, QueryRetrieverService, QueryUploadService, SystemTemplatesService, TemplateUploadService
    public abstract class WebService
extends java.lang.Object
    Base class for web services. See methods of class to be able implement subclass.

    Output

    There can be 3 types of output:
    • Only Error output
    • Complete results - xml, tab separated, html
    • Incomplete results - error messages are appended at the end

    Web service design

    • Request is parsed with corresponding RequestProcessor class and returned as a corresponding Input class.
    • Web services are subclasses of WebService class.
    • Web services use implementations of Output class to print results.
    • Request parameter names are constants in corresponding RequestProcessorBase subclass.
    • Servlets are used only for forwarding to corresponding web service, that is created always new. With this implementation fields of new service are correctly initialized and there don't stay values from previous requests.
    For using of web services see InterMine wiki pages.
    Author:
    Jakub Kulaviak, Alex Kalderimis

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Output dataPackageOutput  
      static java.lang.String DEFAULT_CALLBACK
      Default jsonp callback
      protected InterMineAPI im
      The configuration object.
      protected java.io.OutputStream os  
      protected java.io.PrintWriter out  
      protected Output output
      The response to the outside world.
      protected javax.servlet.http.HttpServletRequest request
      The servlet request.
      protected javax.servlet.http.HttpServletResponse response
      The servlet response.
      protected java.util.Properties webProperties
      The properties this mine was configured with

    • Constructor Summary

      Constructors 
      Constructor Description
      WebService​(InterMineAPI im)
      Construct the web service with the InterMine API object that gives access to the core InterMine functionality.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected boolean canServe​(Format format)
      Check whether the format is acceptable.
      protected void cleanUp()
      Subclasses may put clean-up code here, to be run after the request has been executed.
      protected abstract void execute()
      Runs service.
      protected boolean formatIsFlatFile()  
      protected boolean formatIsJSON()  
      protected boolean formatIsJSONP()  
      boolean formatIsXML()  
      protected Profile getAuthenticatedUser()
      Get a profile that is a true authenticated user that exists in the database.
      java.lang.String getCallback()
      Get the value of the callback parameter.
      ColumnHeaderStyle getColumnHeaderStyle()
      Get an enum which represents the column header style (path, friendly, or none)
      protected java.lang.String getDefaultFileName()  
      protected Format getDefaultFormat()  
      protected Output getDefaultOutput​(java.io.PrintWriter out, java.io.OutputStream os)
      Make the default output for this service.
      protected Output getDefaultOutput​(java.io.PrintWriter out, java.io.OutputStream os, java.lang.String separator)
      Make the default output for this service.
      protected java.lang.String getExtension()  
      Format getFormat()
      Returns required output format.
      protected java.lang.Integer getIntParameter​(java.lang.String name)
      Get the value of a parameter that should be interpreted as an integer.
      protected java.lang.Integer getIntParameter​(java.lang.String name, java.lang.Integer defaultValue)
      Get the value of a parameter that should be interpreted as an integer.
      java.lang.String getLineBreak()  
      protected ListManager getListManager()  
      protected java.lang.String getOptionalParameter​(java.lang.String name)
      Get a parameter this service deems to be optional, or null.
      protected java.lang.String getOptionalParameter​(java.lang.String name, java.lang.String defaultValue)
      Get a parameter this service deems to be optional, or the default value.
      protected ProfileManager.ApiPermission getPermission()
      Return the permission object representing the authorisation state of the request.
      protected java.lang.String getProperty​(java.lang.String name)
      Get a configuration property by name.
      protected java.io.PrintWriter getRawOutput()
      Get access to the underlying print-writer.
      protected java.lang.String getRequestFileName()
      If the request has a filename parameter then use that for the fileName, otherwise use the default fileName
      protected java.lang.String getRequiredParameter​(java.lang.String name)
      Get a parameter this service deems to be required.
      boolean hasCallback()
      Determine whether a callback was supplied to this request.
      protected void initState()
      Subclasses can put initialisation here.
      boolean isAuthenticated()  
      protected boolean isGzip()  
      protected boolean isUncompressed()  
      protected boolean isZip()  
      protected Output makeJSONOutput​(java.io.PrintWriter out, java.lang.String separator)
      Make the default JSON output given the HttpResponse's PrintWriter.
      protected Output makeXMLOutput​(java.io.PrintWriter out, java.lang.String separator)
      Make the XML output given the HttpResponse's PrintWriter.
      protected void postInit()
      Subclasses can hook in here to do common behaviour that needs to happen after initialisation.
      void service​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
      Starting method of web service.
      protected void setFormat​(Format format)
      For very picky services, you can just set it yourself, and say "s****w you requester".
      protected void setNameSpace​(java.lang.String namespace)
      Set the default name-space for configuration property look-ups.
      protected void validateState()
      Subclasses can put initialisation checks here.
      boolean wantsColumnHeaders()
      Returns true if the request wants column headers as well as result rows
      protected boolean wantsDataPackage()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DEFAULT_CALLBACK

        public static final java.lang.String DEFAULT_CALLBACK
        Default jsonp callback
        See Also:
        Constant Field Values

      • request

        protected javax.servlet.http.HttpServletRequest request
        The servlet request.

      • response

        protected javax.servlet.http.HttpServletResponse response
        The servlet response.

      • output

        protected Output output
        The response to the outside world.

      • dataPackageOutput

        protected Output dataPackageOutput

      • os

        protected java.io.OutputStream os

      • im

        protected final InterMineAPI im
        The configuration object.

      • webProperties

        protected final java.util.Properties webProperties
        The properties this mine was configured with

      • out

        protected java.io.PrintWriter out

    • Constructor Detail

      • WebService

        public WebService​(InterMineAPI im)
        Construct the web service with the InterMine API object that gives access to the core InterMine functionality.
        Parameters:
        im - the InterMine application

    • Method Detail

      • getPermission

        protected ProfileManager.ApiPermission getPermission()
        Return the permission object representing the authorisation state of the request. This is guaranteed to not be null.
        Returns:
        A permission object, from which a service may inspect the level of authorisation, and retrieve details about whom the request is authorised for.

      • getRequiredParameter

        protected java.lang.String getRequiredParameter​(java.lang.String name)
        Get a parameter this service deems to be required.
        Parameters:
        name - The name of the parameter
        Returns:
        The value of the parameter. Never null, never blank.
        Throws:
        MissingParameterException - If the value of the parameter is blank or null.

      • getOptionalParameter

        protected java.lang.String getOptionalParameter​(java.lang.String name,
                                                java.lang.String defaultValue)
        Get a parameter this service deems to be optional, or the default value.
        Parameters:
        name - The name of the parameter.
        defaultValue - The default value.
        Returns:
        The value provided, if there is a non-blank one, or the default value.

      • getAuthenticatedUser

        protected Profile getAuthenticatedUser()
        Get a profile that is a true authenticated user that exists in the database.
        Returns:
        The user's profile.
        Throws:
        ServiceForbiddenException - if this request resolves to an unauthenticated profile.

      • getListManager

        protected ListManager getListManager()
        Returns:
        A ListManager for this user.

      • getOptionalParameter

        protected java.lang.String getOptionalParameter​(java.lang.String name)
        Get a parameter this service deems to be optional, or null.
        Parameters:
        name - The name of the parameter.
        Returns:
        The value of the parameter, or null

      • getIntParameter

        protected java.lang.Integer getIntParameter​(java.lang.String name)
        Get the value of a parameter that should be interpreted as an integer.
        Parameters:
        name - The name of the parameter.
        Returns:
        An integer
        Throws:
        BadRequestException - if The value is absent or mal-formed.

      • getIntParameter

        protected java.lang.Integer getIntParameter​(java.lang.String name,
                                            java.lang.Integer defaultValue)
        Get the value of a parameter that should be interpreted as an integer.
        Parameters:
        name - The name of the parameter.
        defaultValue - The value to return if none is provided by the user.
        Returns:
        An integer

      • setNameSpace

        protected void setNameSpace​(java.lang.String namespace)
        Set the default name-space for configuration property look-ups. If a value is set, it must be provided before any actions are taken. This means this property must be set before the execute method is called.
        Parameters:
        namespace - The name space to use (eg: "some.namespace"). May not be null.

      • getProperty

        protected java.lang.String getProperty​(java.lang.String name)
        Get a configuration property by name.
        Parameters:
        name - The name of the property to retrieve.
        Returns:
        A configuration value.

      • service

        public void service​(javax.servlet.http.HttpServletRequest request,
                    javax.servlet.http.HttpServletResponse response)
        Starting method of web service. The web service should be run like 
         new ListsService().service(request, response);
        Ensures initialisation of web service and makes steps common for all web services and after that executes the execute method, for which each subclass must provide an implementation.
        Parameters:
        request - The request, as received by the servlet.
        response - The response, as handled by the servlet.

      • cleanUp

        protected void cleanUp()
        Subclasses may put clean-up code here, to be run after the request has been executed.

      • initState

        protected void initState()
        Subclasses can put initialisation here.

      • validateState

        protected void validateState()
        Subclasses can put initialisation checks here. The main use case is for confirming authentication.

      • postInit

        protected void postInit()
        Subclasses can hook in here to do common behaviour that needs to happen after initialisation.

      • formatIsJSON

        protected final boolean formatIsJSON()
        Returns:
        Whether or not the requested result format is one of our JSON formats.

      • formatIsJSONP

        protected final boolean formatIsJSONP()
        Returns:
        Whether or not the format is a JSON-P format

      • formatIsFlatFile

        protected final boolean formatIsFlatFile()
        Returns:
        Whether or not the format is a flat-file format

      • formatIsXML

        public boolean formatIsXML()
        Returns:
        Whether or not the format is XML.

      • makeXMLOutput

        protected Output makeXMLOutput​(java.io.PrintWriter out,
                               java.lang.String separator)
        Make the XML output given the HttpResponse's PrintWriter.
        Parameters:
        out - The PrintWriter from the HttpResponse.
        separator - the line-separator for the client's platform.
        Returns:
        An Output that produces good XML.

      • makeJSONOutput

        protected Output makeJSONOutput​(java.io.PrintWriter out,
                                java.lang.String separator)
        Make the default JSON output given the HttpResponse's PrintWriter.
        Parameters:
        out - The PrintWriter from the HttpResponse.
        separator - The line-separator for the client's platform.
        Returns:
        An Output that produces good JSON.

      • isGzip

        protected boolean isGzip()
        Returns:
        Whether or not this request wants gzipped data.

      • isZip

        protected boolean isZip()
        Returns:
        Whether or not this request wants zipped data.

      • isUncompressed

        protected boolean isUncompressed()
        Returns:
        Whether or not this request wants uncompressed data.

      • wantsDataPackage

        protected boolean wantsDataPackage()
        Returns:
        Whether or not this request wants to export data package.

      • getExtension

        protected java.lang.String getExtension()
        Returns:
        the file-name extension for the result-set.

      • getRawOutput

        protected java.io.PrintWriter getRawOutput()
        Get access to the underlying print-writer. Most services should not need this method.
        Returns:
        The raw print-writer.

      • getLineBreak

        public java.lang.String getLineBreak()
        Returns:
        The line separator for the client's platform.

      • getDefaultFileName

        protected java.lang.String getDefaultFileName()
        Returns:
        The default file name for this service. (default = "result.tsv")

      • getRequestFileName

        protected java.lang.String getRequestFileName()
        If the request has a filename parameter then use that for the fileName, otherwise use the default fileName
        Returns:
        the fileName to use for the exported file

      • getDefaultOutput

        protected Output getDefaultOutput​(java.io.PrintWriter out,
                                  java.io.OutputStream os,
                                  java.lang.String separator)
        Make the default output for this service.
        Parameters:
        out - The response's PrintWriter.
        os - The Response's output stream.
        separator - The client's line separator.
        Returns:
        An Output. (default = new StreamedOutput(out, new TabFormatter()))

      • getDefaultOutput

        protected Output getDefaultOutput​(java.io.PrintWriter out,
                                  java.io.OutputStream os)
        Make the default output for this service.
        Parameters:
        out - The response's PrintWriter.
        os - The Response's output stream.
        Returns:
        An Output. (default = new StreamedOutput(out, new TabFormatter()))

      • wantsColumnHeaders

        public boolean wantsColumnHeaders()
        Returns true if the request wants column headers as well as result rows
        Returns:
        true if the request declares it wants column headers

      • getColumnHeaderStyle

        public ColumnHeaderStyle getColumnHeaderStyle()
        Get an enum which represents the column header style (path, friendly, or none)
        Returns:
        a column header style

      • getDefaultFormat

        protected Format getDefaultFormat()
        Returns:
        The default format constant for this service.

      • getFormat

        public final Format getFormat()
        Returns required output format. Cannot be overridden.
        Returns:
        format

      • setFormat

        protected void setFormat​(Format format)
        For very picky services, you can just set it yourself, and say "s****w you requester". Use this with caution, and fall-back to getFormat(). Please.
        Parameters:
        format - The format you have decided this request really wants.

      • getCallback

        public java.lang.String getCallback()
        Get the value of the callback parameter.
        Returns:
        The value, or null if this request type does not support this.

      • hasCallback

        public boolean hasCallback()
        Determine whether a callback was supplied to this request.
        Returns:
        Whether or not a callback was supplied.

      • execute

        protected abstract void execute()
                         throws java.lang.Exception
        Runs service. This is abstract method, that must be defined in subclasses and so performs something useful. Standard procedure is overwrite this method in subclasses and let this method to be called from WebService.doGet method that encapsulates logic common for all web services else you can overwrite doGet method in your web service class and manage all the things alone.
        Throws:
        java.lang.Exception - if some error occurs

      • isAuthenticated

        public boolean isAuthenticated()
        Returns:
        true if this request has been authenticated to a specific existing user.

      • canServe

        protected boolean canServe​(Format format)
        Check whether the format is acceptable. By default returns true. Services with a particular set of accepted formats should override this and check.
        Parameters:
        format - The format to check.
        Returns:
        whether or not this format is acceptable.