Module org.cruk.clarity.api
Package org.cruk.clarity.api

Interface ClarityAPI

All Known Implementing Classes:
ClarityAPIImpl
public interface ClarityAPI
Interface to the Clarity API version 2 via REST.

This interface provides the basic methods one would expect to interact with the server via REST. It and the objects under the com.genologics.ri packages hide much of the trickiness from users of this class.

All methods that make calls to the server throw some run time exceptions that client code should expect and handle as appropriate:

  • ClarityException - thrown when the server sends back a response that indicates an exception being raised on the server. The reply is automatically unmarshalled and thrown as this equivalent Java exception.
  • ClarityUpdateException - indicates more an error in client code, where an update is attempted on an entity that does not allow such an update. This can apply to create, update and delete methods. Refer to the REST documentation for details of what is and is not allowed.
  • IllegalStateException - thrown when calls are made to the server before the server URL has been set.
  • HttpClientErrorException - thrown when a call to the server doesn't get as far as being processed. A typical example is when the credentials have not been set.
  • IllegalArgumentException - thrown when parameters that must clearly be given are null. entityClass parameters are a prime example.
See Also:

  • Method Details

    • getServer

      URL getServer()
      Get the base URL of the Clarity server. This does not include the path to the API, just the protocol, host and port.
      Returns:
      The server base URL.
      Throws:
      IllegalStateException - if the API has not been configured.

    • setServer

      void setServer(URL serverAddress)
      Set the base URL to the Clarity server.
      Parameters:
      serverAddress - The base URL. Should just be the protocol, host and port with no path.
      Throws:
      IllegalArgumentException - if serverAddress is null.

    • getServerApiAddress

      String getServerApiAddress()
      Get the base address of the REST API. This is the server base address plus the API path (/api/v2).
      Returns:
      The API base address.

    • getUsername

      String getUsername()
      Get the user name of the researcher currently connecting to the server.
      Returns:
      The user name used for connections.

    • setCredentials

      void setCredentials(String username, String password)
      Set the credentials to use to connect to the REST API.
      Parameters:
      username - The researcher's user name.
      password - The researcher's password.
      Throws:
      IllegalArgumentException - if username is null.

    • setCredentials

      void setCredentials(Credentials httpCredentials)
      Set the credentials to use to connect to the REST API.
      Parameters:
      httpCredentials - A Credentials object for the HTTP client. Does nothing if this is null.

    • setFilestoreServer

      void setFilestoreServer(String host)
      Set the name of the file store host.
      Parameters:
      host - The name of the file store server.
      Throws:
      IllegalArgumentException - if host is empty.

    • setFilestoreCredentials

      void setFilestoreCredentials(String username, String password)
      Set the credentials used to connect to the file store.
      Parameters:
      username - The file store user account.
      password - The file store user password.
      Throws:
      IllegalArgumentException - if username is null.

    • setConfiguration

      void setConfiguration(Properties configuration)
      Set configuration from a properties file. The properties may contain any of the following:

      The properties file does not have to contain all of these values. Any that are missing are simply ignored and, where possible, left as their defaults.

      Parameters:
      configuration - The properties file to configure from.
      Throws:
      InvalidURIException - if the api.server property is set to an invalid URL.

    • setBulkOperationBatchSize

      void setBulkOperationBatchSize(int batchSize)
      Set the number of objects that will be fetched, updated or created in each call the Clarity API for the bulk operations (those that use a collection of links or objects).

      It seems that naively asking for or sending all the links or objects in the collections does not sit well with the back end server. Experimentation has shown that the fastest overall operation time (at least for fetching artifacts) occurs when between twenty and thirty links or artifacts are in the POST call to the Clarity API.

      The default is Genologics' recommendation of a "sweet spot" of 500.

      Parameters:
      batchSize - The number of objects to fetch or send per call to the API. A maximum of 10000 objects per batch is imposed because performance noticeably drops off long before this number of objects is used. If this argument is less than or equal to zero, all object or links in the collection will be sent at once up to the 10000 per call hard limit.
      See Also:

    • setUploadOverHttp

      void setUploadOverHttp(boolean uploadOverHttp)
      Set whether uploads over HTTP are permitted using the files/id/upload API end point, or whether only SFTP uploads are allowed.

      Note that as of release 2.23, downloads from the regular file store take place through the files/id/download end point. This solves any problems for SFTP access to the file store. Files in a HTTP file store may be handled differently (see setDownloadDirectFromHttpStore(boolean)).

      The default is to perform uploads of files no bigger than the limit through HTTP.

      Parameters:
      uploadOverHttp - true if files can be uploaded using HTTP, false if not.
      Since:
      2.23

    • setHttpUploadSizeLimit

      void setHttpUploadSizeLimit(long limit)
      Set the maximum size of file that can be uploaded using HTTP. This must be no greater than the corresponding Clarity configuration property api.artifacts.max.resultfile.upload.size.

      The default file size limit is 10,485,760 bytes (10MB), which is the default setting for the Clarity configuration property.

      Parameters:
      limit - The maximum size of file allowed over HTTP.
      Throws:
      IllegalArgumentException - if limit is less than one.
      Since:
      2.23

    • setAutoRevertToSFTPUploads

      void setAutoRevertToSFTPUploads(boolean autoRevertToSFTP)
      Set whether the SFTP mechanism can be used as a fall back for uploading files if a file exceeds the HTTP upload size limit.

      The default is to allow the SFTP upload mechanism to be used if a file is too large for HTTP.

      Parameters:
      autoRevertToSFTP - true to use SFTP to transfer files that are too large for HTTP, false to fail if such a file is given.
      Since:
      2.23
      See Also:

    • setDownloadDirectFromHttpStore

      void setDownloadDirectFromHttpStore(boolean downloadDirect)
      For files stored in a HTTP file store, set whether to download these files directly from their HTTP server or whether to fetch them via the API's files/id/download end point (i.e. the same as files in the regular file store).

      The default is to download directly from the HTTP store rather than going through the API. This will save traffic and load on the LIMS server.

      Parameters:
      downloadDirect - true to fetch HTTP accessible files directly from their HTTP URL, false to fetch them via the Clarity API.
      Since:
      2.23

    • limsIdToUri

      <E extends Locatable> URI limsIdToUri(String limsid, Class<E> entityClass)
      Convert the given LIMS id to a full URI for that entity.

      This method is for the most common entities in the API where the URIs are simply of the form <endpoint>/<limsid>.

      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      limsid - The LIMS id of the entity required.
      entityClass - The class of the entity.
      Returns:
      The full URI to the entity.
      Throws:
      InvalidURIException - if the creation of the URI gives a malformed URI.
      IllegalArgumentException - if either argument is null, or if entityClass is annotated with a primary section attribute.
      See Also:

    • limsIdToUri

      <E extends Locatable> URI limsIdToUri(String outerLimsid, String innerLimsid, Class<E> entityClass)
      Convert the given LIMS ids to a full URI for that entity.

      This method is for use on entities that have been annotated to indicate they are part of a larger entity, for example ProtocolStep within Protocol or Stage within Workflow.

      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      outerLimsid - The LIMS id of the outer endpoint of the URI.
      innerLimsid - The LIMS id of the inner endpoint of the URI.
      entityClass - The class of the entity.
      Returns:
      The full URI to the entity.
      Throws:
      InvalidURIException - if the creation of the URI gives a malformed URI.
      IllegalArgumentException - if any argument is null, or if entityClass is not annotated with a primary section attribute.
      Since:
      2.22

    • nextCallCacheOverride

      @Deprecated void nextCallCacheOverride(CacheStatefulBehaviour behaviour)
      Deprecated.
      Calls through to overrideStateful(StatefulOverride) with a conversion of the behaviour value to StatefulOverride, so behaviour is maintained but one should update code to use overrideStateful.
      This method was used to overrides the cache behaviour for the next call on the same thread. It has been replaced by overrideStateful(StatefulOverride) which does the correct thing. Momentarily changing how the cache worked didn't solve the problem this was intended for (up to date QC flags on artifacts).

      The values map as:

      1. CacheStatefulBehaviour.EXACT becomes StatefulOverride.EXACT.
      2. CacheStatefulBehaviour.LATEST becomes StatefulOverride.LATEST.
      3. CacheStatefulBehaviour.ANY or null clears the override.
      Parameters:
      behaviour - The cache behaviour for the next call from the current thread.
      Since:
      2.24.3

    • overrideStateful

      void overrideStateful(StatefulOverride override)
      Forces the API to fetch stateful entities according to the rule given for the next API call only.

      Calling this method only applies the change to the next call to the API on the current thread. After the call, the API returns to normal behaviour (fetching the entity with the state indicated by the URI). If this method is invoked and entities that are not stateful are requested, the call here has no effect. It is not remembered for the next stateful entity request, so make sure the code calls this immediately before the call it is needed for.

      In practice, this is useful only for the QC flags from artifacts. One would either need the flag as specified by the URI exactly, or would want the flag in its current state rather than the state given in the URI.

      Parameters:
      override - The behaviour to use in the next call. If null, it will cancel a previously set override.
      Since:
      2.24.8

    • listAll

      <E extends Locatable> List<LimsLink<E>> listAll(Class<E> entityClass)
      List all the objects of the given entity class.
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      entityClass - The type of entity to list.
      Returns:
      A list of links to the real entities in the LIMS.
      Throws:
      IllegalArgumentException - if entityClass is annotated to be a part of another entity (its primaryEntity attribute is set).

    • listSome

      <E extends Locatable> List<LimsLink<E>> listSome(Class<E> entityClass, int startIndex, int number)
      List an arbitrary number of objects of the given entity class. This is not all that helpful for most real applications but can be very handy for test cases.
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      entityClass - The type of entity to list.
      startIndex - The index of the first item to fetch. This start number is zero-based.
      number - The number of items to fetch.
      Returns:
      A list of links to the real entities in the LIMS. This may be fewer in number than number if there are too few items to fetch.
      Throws:
      IllegalArgumentException - if entityClass is annotated to be a part of another entity (its primaryEntity attribute is set).

    • find

      <E extends Locatable> List<LimsLink<E>> find(Map<String,?> searchTerms, Class<E> entityClass)
      Search for entities of the given type based on name value pairs. The query string is built up from the search terms. Where the term value is an array or collection, the term is added multiple times which Clarity interprets as an OR. For example, if the map contains: 
       "projectname" : [ "projectA", "projectB" ]
      then the search will be for entities whose projectname attribute is "projectA" or "projectB".
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      searchTerms - The terms to use for the search.
      entityClass - The type of entity to list.
      Returns:
      A list of links to the real entities in the LIMS.
      Throws:
      IllegalSearchTermException - if any term in searchTerms is found to be illegal. See IllegalSearchTermException for details of what is illegal.
      IllegalArgumentException - if entityClass is annotated to be a part of another entity (its primaryEntity attribute is set).

    • retrieve

      <E extends Locatable> E retrieve(String uri, Class<E> entityClass)
      Retrieve an entity using a String form of its URI.

      Note that when this method is used (as opposed to its equivalent taking a URI object) Spring's REST template performs escaping on the URI string so that special characters are sent to be literally that character. This is typically what is wanted for a first call, but using this method to navigate from the server's response can cause problems (especially with searches). Subsequent calls using links returned from the server should use the variant of this method that accepts a URI object.

      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      uri - The URI to retrieve, in string form.
      entityClass - The type of entity to list.
      Returns:
      The LIMS entity.
      Throws:
      InvalidURIException - if uri is not a valid URI.
      See Also:

    • retrieve

      <E extends Locatable> E retrieve(URI uri, Class<E> entityClass)
      Retrieve an entity by its URI.
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      uri - The URI to retrieve.
      entityClass - The type of entity to list.
      Returns:
      The LIMS entity.
      See Also:

    • load

      <E extends Locatable> E load(String limsid, Class<E> entityClass)
      Load an entity by its LIMS id. The URI of the object is created based on this interface's currently set server address, the type of the object requested and the LIMS id given.
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      limsid - The LIMS id of the entity.
      entityClass - The type of entity to list.
      Returns:
      The LIMS entity.

    • load

      <E extends Locatable> E load(String outerLimsid, String innerLimsid, Class<E> entityClass)
      Load an entity by its two required LIMS ids. The URI of the object is created based on this interface's currently set server address, the type of the object requested and the LIMS ids given.

      This method is for use on entities that have been annotated to indicate they are part of a larger entity, for example ProtocolStep within Protocol or Stage within Workflow.

      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      outerLimsid - The LIMS id of the outer endpoint of the URI.
      innerLimsid - The LIMS id of the inner endpoint of the URI.
      entityClass - The type of entity to list.
      Returns:
      The LIMS entity.
      Since:
      2.22

    • load

      <E extends Locatable> E load(LimsLink<E> link)
      Load an entity using a link to that entity. Typically, the link object will come from a search or another object already fetched from the LIMS.
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      link - The link to the LIMS entity.
      Returns:
      The LIMS entity.

    • loadAll

      <E extends Locatable> List<E> loadAll(Collection<? extends LimsLink<E>> links)
      Fetch a collection of LIMS entities given in the collection. The order of the returned entities is the same as the iteration order of the links collection.

      Using this method to fetch several entities at once can be beneficial where the Clarity API allows batch fetching of objects. Rather than making a call for each link, the links are collected into a single call whose response is all the entities for the links. For those entities where this is not possible, a call is made for each link. The end result is the same.

      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      links - The collection of links to the entities.
      Returns:
      A list of the LIMS entities.

    • reload

      <E extends LimsEntity<E>> void reload(E entity)
      Reload an entity in-situ. The given object is refreshed from the server.
      Type Parameters:
      E - The type of LIMS entity referred to.
      Parameters:
      entity - The LimsEntity to refresh.

    • create

      <E extends Locatable> void create(E entity)
      Create an instance of the given entity on the server.

      When successful, the entity's fields are all updated based on the values returned in the call's response, so the entity will accurately reflect the object on the server.

      When used with Sample objects, those objects must have an initial location specified using their Sample.setCreationLocation(com.genologics.ri.Location) method.

      Type Parameters:
      E - The type of LIMS entity.
      Parameters:
      entity - The entity object to create in the LIMS.

    • createAll

      <E extends Locatable> void createAll(Collection<E> entities)
      Create a batch of entities on the server.

      When successful, the entities' fields are all updated based on the values returned in the call's response, so each entity will accurately reflect the equivalent object on the server.

      When used with Sample objects, those objects must have an initial location specified using their Sample.setCreationLocation(com.genologics.ri.Location) method.

      Using this method to create several entities at once can be beneficial where the Clarity API allows batch creation of objects. Rather than making a call for each object, the objects are collected into a single call whose response is information on the entities now present in the server. For those entities where this is not possible, a call is made for each object. The end result is the same.

      Type Parameters:
      E - The type of LIMS entity.
      Parameters:
      entities - The entity objects to create in the LIMS.

    • update

      <E extends Locatable> void update(E entity)
      Update the given entity on the server. The fields that can be updated differ between entities: refer to the Clarity REST documentation for details.

      When successful, the entity's fields are all updated based on the values returned in the call's response, so the entity will accurately reflect the object on the server.

      Type Parameters:
      E - The type of LIMS entity.
      Parameters:
      entity - The entity to update.

    • updateAll

      <E extends Locatable> void updateAll(Collection<E> entities)
      Updates a batch of entities.

      When successful, the entities' fields are all updated based on the values returned in the call's response, so each entity will accurately reflect the equivalent object on the server.

      Using this method to update several entities at once can be beneficial where the Clarity API allows batch update of objects. Rather than making a call for each object, the objects are collected into a single call whose response is information on the entities now present in the server. For those entities where this is not possible, a call is made for each object. The end result is the same.

      Type Parameters:
      E - The type of LIMS entity.
      Parameters:
      entities - The entities to update.

    • delete

      <E extends Locatable> void delete(E entity)
      Deletes an entity from the server.

      When successful, the entity object should no longer be used.

      Type Parameters:
      E - The type of LIMS entity.
      Parameters:
      entity - The entity to delete.

    • deleteAll

      <E extends Locatable> void deleteAll(Collection<E> entities)
      Deletes a batch of entities from the server.

      When successful, the entity objects should no longer be used.

      Type Parameters:
      E - The type of LIMS entity.
      Parameters:
      entities - The entities to delete.

    • executeProcess

      ClarityProcess executeProcess(ExecutableProcess toExecute)
      Execute a process within the LIMS. The given executable process object needs to be set up carefully for this to work. Refer to the Clarity documentation.
      Parameters:
      toExecute - The executable process with all the information of what is to run.
      Returns:
      The ClarityProcess object reflecting the process record in the LIMS.
      See Also:

    • beginProcessStep

      ProcessStep beginProcessStep(StepCreation stepCreation)
      Start a protocol step as if running through Clarity.
      Parameters:
      stepCreation - The step creation object. See Genologics' API documentation.
      Returns:
      The ProcessStep object for the step started.
      Throws:
      IllegalArgumentException - if stepCreation is null.
      See Also:

    • advanceProcessStep

      void advanceProcessStep(ProcessStep step)
      Move the process step to its next stage.

      Note that how the step advances is very dependent on the state it is currently in. For example, one may have to set values on the Actions object and update that before a step can advance past "next steps". Again, refer to the API documentation.

      Parameters:
      step - The step to advance. The state of this object is updated in place.
      See Also:

    • startProgram

      ProgramStatus startProgram(AvailableProgram program)
      Start execution of an EPP as part of a process step moving through Clarity.
      Parameters:
      program - The program, as listed in the ProcessStep object.
      Returns:
      An updated program status structure.
      Since:
      2.27.5
      See Also:

    • currentStatus

      void currentStatus(ProgramStatus status)
      Get an updated program status from Clarity.
      Parameters:
      status - The program status to update. The object is updated in place with the latest values.
      Since:
      2.27.5

    • uploadFile

      <E extends LimsEntity<E>> ClarityFile uploadFile(LimsEntityLinkable<E> entity, URL fileURL, boolean publishInLablink) throws IOException
      Attach a file to an entity and upload that file to the file store.

      The client can be configured to use either the existing SFTP mechanism for the upload or the HTTP upload end point added in Clarity 4.0. Care should be taken with this choice, as the older mechanism is either safer or more problematic, depending on one's viewpoint.

      Uploading over HTTP has the additional issue that adding a file to a completed process fails. This is not a restriction of the SFTP upload.

      There is a maximum size that Clarity will accept for a file uploaded over HTTP (see setHttpUploadSizeLimit(long)). The client can be configured to drop back to SFTP if this size is exceeded. Alternatively it can be configured to never use the HTTP mechanism or to fail if the file is too big.

      Type Parameters:
      E - The type of LIMS entity the file is being attached to.
      Parameters:
      entity - The LIMS entity to attach the file to.
      fileURL - The URL of the file (relative to the local file system where relevant). This forms the original location part of the file record.
      publishInLablink - Whether the file should be displayed in the LabLink interface.
      Returns:
      The file record in the Clarity LIMS.
      Throws:
      IOException - if the file read or write fails.
      See Also:

    • downloadFile

      void downloadFile(Linkable<ClarityFile> file, OutputStream resultStream) throws IOException
      Download the given file from its source. Its content is written out to resultStream.
      Parameters:
      file - The file to fetch.
      resultStream - The OutputStream to write the file content to.
      Throws:
      IOException - if there is a problem with the download.
      InvalidURIException - if the download URI string internally created to fetch the file isn't a valid URI (shouldn't happen).

    • deleteAndRemoveFile

      void deleteAndRemoveFile(Linkable<ClarityFile> file) throws IOException
      Delete a file from the file store and remove its record from the LIMS. If the file is not in the file store, only its record is removed.
      Parameters:
      file - The file to delete.
      Throws:
      IOException - if there is a problem removing the file from the file store.

    • routeArtifacts

      void routeArtifacts(Routing routing)
      Issue a routing request for artifacts into workflows. Routing is a funny object that is post only and doesn't fit with "create".
      Parameters:
      routing - The Routing object that has been assembled.

    • listQueue

      List<LimsEntityLink<Artifact>> listQueue(Linkable<ProtocolStep> protocolStep)
      List the artifacts in the queue for the given protocol step.
      Parameters:
      protocolStep - The protocol step of the queue (or a link to it).
      Returns:
      Links to the artifacts currently in the given queue.
      Since:
      2.22

    • listQueue

      List<LimsEntityLink<Artifact>> listQueue(Linkable<ProtocolStep> protocolStep, Map<String,?> searchTerms)
      List the artifacts in the queue for the given protocol step, additionally filtering using the parameters available for the "queues" end point.

      Search terms work the same as for the find(Map, Class) method. Also see Genologics' documentation of this end point for the options available.

      Parameters:
      protocolStep - The protocol step of the queue (or a link to it).
      searchTerms - The terms to use for the search.
      Returns:
      Links to the artifacts currently in the given queue that meet the criteria of the search terms.
      Since:
      2.24.1