Programmatic Access

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 (base 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., DbManagerFactory), we recommend to use the use the Resource class, which is based on Spring Framework and allow 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 below.

##Linking via Maven If you use 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.0.1-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. This is 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 module (the .zip that is created in target after 'mvn package'). Parameterised versions of such file 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 We do not officially support builds outside Maven, but in case 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 (change the version to a proper value), or build it from the myequivalents sources, going to root and issuing 'mvn package' (the final jar will be somewhere like myequivalents-db/target/).
  • 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).

##Using the 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();

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"
);

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()