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

Programmatic Access

Jump to bottom
Marco Brandizi edited this page Feb 24, 2014 · 34 revisions

As mentioned above, the myequivalents-core contains the definition of general interfaces to access the myEquivalents functionality. The core module contains only such abstract interfaces and a configuration mechanism (based on Spring) to create and obtain specific instances of such interfaces. You must select a specific implementation, such as the one available from the myequivalents-db module, in order to make things working.

The entry point to myEquivalents is the manager factory. This uses the factory pattern to get managers to pieces or functionality. While you can explicitly instantiate a specific implementation of the manager factory (e.g., new DbManagerFactory(...)), we recommend to use the Resource class, which is based on Spring Framework and allows you to define the specific manager factory that you need in a Spring metadata configuration file. This is a powerful and flexible mechanism, as it is shown in the configuration section.

##Linking myEquivalents to your application, via Maven If your application is built through Maven, as we recommend, the details are as follow.

  • Use the EBI repository in your Maven's POM:
<repository>
  <id>ebi-repo</id>
  <name>EBI repo</name>
  <url>http://www.ebi.ac.uk/~maven/m2repo</url>
</repository>
  • Declare the core dependency, or, more realistically, a dependency on a specific implementation:
<dependency>
  <groupId>uk.ac.ebi.fg</groupId>
  <artifactId>myequivalents-db</artifactId>
  <version>0.2-SNAPSHOT</version><!-- or the last version! -->
</dependency>
  • To use the Spring-based configuration mechanism, make a file like myeq-manager-config.xml available to the Java classpath. In Maven, this file is usually located into src/main/resources or src/test/resources. An example copy of such file can be taken from the binary build for the myequivalents-cmdline distribution. Parameterised versions of such file (which are populated with real value by Maven profiles) are in the db module.

This is a Spring metadata file that defines the bean named myEquivalentsManagerFactory, an instance of the ManagerFactory interface. The default version of such file instantiates the DbManagerFactory class, the implementation based on a relational database. You can define Hibernate and connection parameters for such factory class straight in such metadata file.

##Linking as a .jar While do not officially support builds outside Maven, if that is your case, the following should work.

  • Download the core .jar, from here.
  • Download the .jar corresponding to the back-end that you need, for example the relational back-end, or build it from the myequivalents sources, going to root and issuing 'mvn package' (the final jar will be somewhere like myequivalents-db/target/, see building instructions for details).
    • Note that these jar files contain only the myEquivalents core functionality and not 3rd party dependencies, which you can list from the POM at the same URL. If you want a .jar containing all that is needed, build the command-line module and get myequivalents_deps.jar from the target/ directory.
  • Define a proper myeq-manager-config.xml metadata file for your project, as explained above, and put it in the classpath (or link it to your project the way recommended by your IDE).

##Obtaining Managers The following examples are mostly taken from our JUnit tests. You should access the myEquivalents system starting from getting the pre-configured manager factory:

ManagerFactory mgrFactory = Resources.getInstance ().getMyEqManagerFactory ();

This will lead you to the bean named myEquivalentsManagerFactory and defined in the myeq-manager-config.xml file. Once you have a factory, you can get the manager you need, for instance:

ServiceManager serviceMgr = mgrFactory.newServiceManager();
// Of course you can do it quicker: 
// ServiceManager serviceMgr = Resources.getInstance ().getMyEqManagerFactory ().newServiceManager();

##Obtaining Managers, with authentication The code examples above grant read-only access to myEquivalents public data. This is because they don't specify any user to log in into the myEquivalents system who has proper rights for accessing reserved data or make changes. In fact, when no such user is given to the above code to acquire managers, myEquivalents implicitly link your invoking code to a special, anonymous user, who has minimal rights.

In order to log in with another user, you have to use the following code.

ServiceManager serviceMgr = mgrFactory.newServiceManager ( "[email protected]", "test.secret" );

###Types of authentication The call in this example makes a 'API-related authentication', i.e., an kind of myEquivalents login that can be used to access myEquivalents mappings and related operations. A 'password secret' is associated to a myEquivalents user that can be used for this type of authentication.

There is another type of myEquivalents login, available for the [AccessControlManager](TODO: link), the full user authentication:

AccessControlManager accMgr = mgrFactory.newAccessControlManagerFullAuth ( "[email protected]", "test.secret" );

when you login in full mode, you have additional access to your account, for example to change your name or your passwords. The idea of having two login types is that the full authentication is more critical and should not be used for most common operations, which are typically present in your client code. In future, we plan to develop a web interface to access user-administration and similar actions. In such a scenario, the full authentication will typically used by human beings via such interface, while the regular authentication will be reserved to user's applications.

###User roles and access levels TODO

## Service-related interfaces Defining a new service

service1 = new Service ( "test.testservmgr.service1", "testservmgr.someType1", "A Test Service 1", "The Description of a Test Service 1" );
service1.setUriPrefix ( "http://somewhere.in.the.net/testservmgr/service1/" );
service1.setUriPattern ( 
  "http://somewhere.in.the.net/testservmgr/service1/someType1/${accession}" );

sc1 = new ServiceCollection ( 
  "test.testservmgr.serviceColl1", service1.getEntityType (), "Test Service Collection 1", 
  "The Description of the SC 1" 
);
service1.setServiceCollection ( sc1 );

repo1 = new Repository ( "test.testservmgr.repo1", "Test Repo 1", "The Description of Repo1" );
service1.setRepository ( repo1 );

service2 = new Service (...);

serviceMgr.storeServices ( service1, service2 );

Service-related information can also be uploaded by using XML, pretty much the same way you do with the command line (see below):

String xml =
"<service-items>\n" +
"  <services>\n" +
"    <service uri-pattern='http://somewhere.in.the.net/testservmgr/service6/someType1/${accession}'\n" + 
"           uri-prefix='http://somewhere.in.the.net/testservmgr/service6/'\n" + 
"           entity-type='testservmgr.someType1' title='A Test Service 6' name='test.testservmgr.service6'>\n" +
"      <description>The Description of a Test Service 6</description>\n" + 
"    </service>\n" + 
"    <service entity-type='testservmgr.someType7' title='A Test Service 7' name='test.testservmgr.service7'" +
"           repository-name = 'test.testservmgr.repo1'" +
"           service-collection-name = 'test.testservmgr.serviceColl1'>\n" +
"      <description>The Description of a Test Service 7</description>\n" +
"    </service>\n" +
"    <service uri-prefix='http://somewhere-else.in.the.net/testservmgr/service8/'\n" +
"             entity-type='testservmgr.someType2' title='A Test Service 8' name='test.testservmgr.service8'>\n" + 
"      <description>The Description of a Test Service 8</description>\n" + 
"    </service>\n" +
"  </services>\n" +
"</service-items>";

serviceMgr.storeServicesFromXML ( new StringReader ( xml ) );

Fetching services by name

ServiceSearchResult result = serviceMgr.getServices ( 
  "test.testservmgr.service6", "test.testservmgr.service7", "test.testservmgr.service8" );
for ( Service service: result.getServices () )
  // service object accessible here

ServiceManager can also be used to lookup service-collections ( getServiceCollections() ) and repositories( getRepositories() ) by name.

ServiceManager also contains methods to delete services ( deleteServices() ) and related objects.

Storing mappings

EntityMappingManager emMgr = Resources.getInstance ().getMyEqManagerFactory ().newEntityMappingManager();

// bundle b1 ( (s1, b1.1) (s2, b1.2) (s1, b1.3)
// bundle b2 ( (s2, b2.1) (s3, b2.2) )

// Stores a whole equivalence class (a bundle)
emMgr.storeMappingBundle ( 
  service1.getName () + ":b1.1", service2.getName () + ":b1.2", service1.getName () + ":b1.3" );

// Store a pair of entities that are linked together (i.e., are equivalent)
emMgr.storeMappings ( 
  service2.getName () + ":b2.1", service3.getName () + ":b2.2"
);

##Mapping-related interfaces Fetching mappings*

// Fetches all the bundles each of the parameter entities belongs to
EntityMappingSearchResult result = emMgr.getMappings ( 
  false, service1.getName () + ":b1.3", service3.getName () + ":b2.2" 
);

for ( Bundle bset: result.getBundles () )
  for ( Entity entity: bset.getEntities () )
    // entity.getService() and entity.getAccession()

##User and permission administration TODO

Clone this wiki locally