Skip to content
This repository was archived by the owner on Jan 9, 2023. It is now read-only.

Architecture

Jump to bottom
Marco Brandizi edited this page Jan 26, 2017 · 19 revisions

#myEquivalents Rationale and Data model

This is explained in these slides.

#Two Types of Entity identifiers

the entities that myEquivalents is able to link each other can be identified in one of the following ways:

  • by referring to the service they belong, and by providing their accession within such service. As usually, accessions are identifiers that are unique within a given service (they might be unique world-wide, but this is not required). When entities are identified this way, the syntax: serviceName:accession is used. For instance: arrayExpress.experiments:E-GEOD-23332 means the entity E-GEOD-23332 within the service 'arrayExpress.experiments'. Of course, in practice this example refers to the experiment E-GEOD-23332 coming from the ArrayExpress gene expression database, however myEquivalents is completely agnostic of what an entity or service actually means, with this identifier format, the links to the actual service/entities are established in the service definition, where, in this case, a description of what an ArrayExpress experiment is is provided and, most importantly, the URI pattern that, instantiated with a valid accession like E-GEOD-23332, lands to the web page of that AE experiment, so in this case the pattern http://www.ebi.ac.uk/arrayexpress/experiments/$id, defined in the arrayExpress.experiments service, would allow myEquivalents to build the URI http://www.ebi.ac.uk/arrayexpress/experiments/E-GEOD-23332 for E-GEOD-23332 (yes, we use the same syntax that MIRAM uses for URI patterns). Multiple services provided by the same repository/web site can be linked to a repository description (i.e., a myEquivalents arrayExpress repository in this case). This explanation implies that services must be defined in myEquivalents prior to starting using them in entity identifiers.

  • by providing the straight URI of an entity. URIs are a well-established standard, used by both the World Wide Web and the Semantic Web technologies to universally identify web resources. in myEquivalents a URI that identifies an entity can be provided by means of the syntax: (which, of course, is inspired to RDF languages, like N3 or Turtle). For instance, the URI about previous AE example would be <http://www.ebi.ac.uk/arrayexpress/experiments/E-GEOD-23332>. When such syntax is used, myEquivalents makes an effort to find a defined service that the URI corresponds to. For instance, it would match our example URI with the arrayExpress.experiments service. This is based on URI patterns and an algorithm that removes the tail of a URI (i.e., all the text after the last separator like '/' or '#', E-GEOD-23332 in this case) and then uses what remains to search services by the URI pattern field. It might happen that no URI pattern/service is found this way, usually this corresponds to the case you don't have a service to map your URI to (or you don't care about attaching a service). If that is the case, myEquivalents maps your URI to a special/fictitious service, the unspecified service, which is defined in myEquivalents during the backend initialisation. This is done ensure homogeneity and to simplify internal procedures. If a URI is particularly tricky, it might happen that a URI pattern/service is not found, despite it being present in myEquivalents. While this is a limit of the way we keep URI and service:accession identifiers together, we think this is unlikely to happen in the real world.

  • by means of the syntax :<URI>, which is equivalent to _:<URI> ('_' is the identifier of the unspecified service). With this syntax, you are explicitly telling myEquivalents that the entity targeted by the URI is not associated to any particular/known service, e.g., :<http://www.ebi.ac.uk/arrayexpress/experiments/E-GEOD-23332>. Because of what is explained at the previous point, myEquivalents associates this kind of URIs to the unspecified service, even if the is another one which of URI pattern matches your URI (the latter is limitation of the system, which allows for simplicity and performance). If you want to use URIs and don't want to deal with services, this syntax is slightly faster than <URI> (because the latter implies that myEquivalents should discover if there is a service associated with the URI.

  • by means of the syntax serviceName:<URI>, in this case myEquivalents verifies that the URI matches the URI pattern stored for the specified service, and triggers an error in case not. This format exists essentially because it is a variant of the previous one and we do not think it will be used in real-life cases.

Further details on how the the entity identity is resolved are available from the code of TODO and its subclasses, which are the components that deals with such resolution. Moreover, in addition to the above note that:

  • once you have stored an entity in a given format (by service+accession, or by URI), myEquivalents is able to convert to the other automatically, so you can query the entity in any way you like, independently on the initial storage. This is indeed one of the main advantages of myEquivalents, compared to other cross-reference software.

  • Note also that, in case a service is associated to a given URI, myEquivalents always extracts the accession from the URI (using the URI pattern associated to the service) and saves the pair, not the initial URI. This makes things more compact and makes it much easier to change/fix all the URIs of a given service in a single operation (i.e., you just need to change the URI pattern, as long as the problem is not with the accessions).

  • Unfortunately, URIs that were saved as linked to the unspecified service are not reconsidered when a service is added (or changed) that has a URI pattern that matches such existing URIs. This is a myEquivalents limit and we plan to add this functionality in a future version.

  • The service lookup implied by the URI syntaxes above is cached, so it will be slow the first time that function is needed for a given service, it will be much faster afterwards. The cache has the same life span of the JVM or application container (i.e., web service) running myEquivalents (i.e., it's defined as a static field in TODO). This means that, unfortunately, there is no cache when you use the command line with the database backend (with the mappings get command), unless you fetch multiple mappings at once.

  • myEquivalents allows you to store two (or more) services having the same URI pattern. However, that is for the benefit of those who are not interested in using URIs as unique identifiers, in a case like this, URI resolution involving one of the services or their URI patterns will not work, because myEquivalents does not know which service should be associated to a URI.

  • at the moment we support URI-based identifiers for mapped entities only. Services, repositories and service collections have only one type of identifier and usually this is an accession (i.e., specific to a myEquivalents instance, organisation or maybe domain). One can always use full URIs as identifiers for such things, what it's not available for them is the dual model of 'accession or URI' and the conversion between the two. This is also a reason why you never use the syntax <URI> to specify an identifier for an element like a service.

#Java Architecture

The myequivalents system is based on Java and the Maven build system. The sources have currently the following Maven modules.

  • the root level myequivalents. As usually, this contains a POM with general definitions, including database profiles that affect the relational database where myequivalents data are stored. The root level contains all the modules listed below as well.
  • myequivalents-core, this contains an object model of the whole system, corresponding to what it is described in the above-mentioned slides, including JPA-based mappings of classes from such model to a relational database and other code to manage such mappings (such as DAOs). The core project contains also high-level interfaces, the managers package, which allows you to access myequivalents functionality, hiding many implementation details. Indeed, unless you want to extend myEquivalents software, you as user should worry about such managers only. As it is shown in the configuration page, managers can be flexibly composed to suit particular application needs. The core package does not contain any particular implementation of such manager interfaces, this is put into the specific Maven modules, described in the follow.
  • myequivalents-db, this contains an implementation of the myEquivalents functionality (i.e., the managers mentioned above) that relies on a relational database. For the moment this is the only storage system available for myEquivalents, we plan to have a SPARQL end-point as an alternative back-end. Being based on Hibernate and JDBC, this implementation allows you to access to a variety of JDBC-compatible databases. We have tested HSQL and Oracle.
  • myequivalents-cmdline, this Maven module builds up a command line package, which can be installed by just unzipping a compressed archive and configuring it with parameters like database connection credentials. By default, both the programmatic access mode and the command line mode are wrappers of a relational database connection (See the configuration section). This implies that you do have access to the relational database that backs myEquivalents.
  • myequivalents-web, this implements a REST, XML-based web service, which makes it possible to access the myEquivalents functionality via the HTTP protocol and without the need to access a backing storage system, such as a relational database. Specifically, this module contains the server side.
  • myequivalents-wscli, this is a client for the web service. If you work with Java, this module gives you a high-level API, which is easier to use than building HTTP requests and parsing the XML that is sent back. Moreover, since both the server and the client side are based on Jersey, accessing the web service via this client is likely less error-prone than accessing it via lower-level code.

See the configuration and composition, page, for information on how to configure and use the different flavours available for myEquivalents.

Go back to the top to list pages about further details on the above components.

Clone this wiki locally