The Web Service Client

The web service client's source is in the Maven module myequivalents/myequivalents-wscli. You can link this module into your project the same way you do it for the core package, the only difference is that 'myequivalents-core' is replaced by 'myequivalents-wscli'.

##Configuration As usually, you should configure the web service client by means of a Spring bean configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
  This is specifically used by the automated tests in the web service client module. myeq-manager-config.xml is instead
  used to setup the web server. This is the easiest arrangement via Maven overlays.  
-->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation=
       	"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
         http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"
>       
	<!--
		This is a Spring Framework resource configuration file (see http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/beans.html).
		 
		The MyEquivalents applications get the managers (i.e. components needed to access the service and its back-end) via 
		the factory configured by this bean. See documentation and test classes in the core package for details.
	-->
	<bean id="myEquivalentsManagerFactory" class="uk.ac.ebi.fg.myequivalents.webservices.client.WSClientManagerFactory">
          <constructor-arg type="java.lang.String" value="http://localhost:8080/myequivalents/ws" />
	</bean>
</beans>

##Usage examples

Once configured as above, the web service client can be used exactly as shown in the programmatic access documentation.

Getting the managers

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

This will point at the URL specified in the Spring configuration file.

Accessing the mappings

This works as any other access mean:

EntityMappingSearchResult result = mmgr.getMappings ( false, "test.testweb.service6:acc1", "test.testweb.service6:acc2" );
// EntityMappingSearchResult is the same class shown in other examples above

Setting up Authentication As usually, When you need data-change operations, you need to send the web service proper authentication credentials for a user that has at least the editor role.

As explained elsewhere, this can be done either when you ask a manager:

ManagerFactory mfact = Resources.getInstance ().getMyEqManagerFactory ();
ServiceManager servMgr = mfact.newServiceManager ( "editor", "editor.secret" );

Or after you got the manager:

String xml =
  "<service-items>\n" +
  "  <services>\n" +
  "    <service uri-pattern='http://somewhere.in.the.net/testweb/service6/someType1/${accession}'\n" +
  ... 

servMgr.setAuthenticationCredentials ( "editor", "editor.secret" );
servMgr.storeServicesFromXML ( new StringReader ( xml ) );

Note that by default the invocation to setAuthenticationCredentials() just prepares account parameters. The actual authentication is done when service's operations are invoked (e.g., storeServicesFromXML()), at that point the previously user/secret are put together with the specific request parameters (an XML in this example) and all is sent to the server side of the web service. There, the credentials will be used to access myEquivalents and invoke the request for the specified user.

In summary, credentials is re-send by every manager's operation invocation and the server redo authentication every time. We have chosen to make it working this way, since this keeps the web layer stateless, i.e., it does not need to create web sessions an maintain cookies or similar trackers on the client side. Performance is not much affected by such an overhead (we are designing caching mechanisms to make it even faster).

WARNING: SSL connections are needed in untrusted networks All the web service requests are sent around via POST requests, so access passwords are never visible from the corresponding URLs. However, if you use non-encrypted HTTP connections, this data can still be intercepted by spoofing HTTP traffic. So, if you are working on a non reliable network (e.g., over the Internet and not with both the client and the server inside your own LAN). We recommend to enforce the usage of the HTTPS protocol.

Do a real authentication when credentials are set

If you wish, you may try an authentication step when setting the credentials:

((ServiceWSClient) servMgr).setAuthenticationCredentials ( "editor", "editor.secret", true );

As you see, this invocation breaks the manager's abstraction (it's a method signature specific of the web service client implementation) and it is rarely useful, so we do not recommend it.

Full authentication

Similarly to other types of interfaces, full authentication is available, for operations like user-data changes:

// Again, no real authentication is made, the parameters are just prepared. 
// The version with the boolean parameter addition is available to and works as described above
AccessControlManager accMgr = Resources.getInstance ().getMyEqManagerFactory ()
  .newAccessControlManagerFullAuth ( "admin.user", "admin.password" );

// Or, first get the manager and then:
// accMgr.setFullAuthenticationCredentials ( "admin.user", "admin.password" );

User user = new User ( 
  "test.user", "Test", "User", "test.pass", "test notes", Role.VIEWER, "test.secret" );
accMgr.storeUser ( user );

##Minor differences between direct access and web service access While we strive to make all possible myEquivalents back ends working exactly the same way and hence interchangeable, there are inevitable minor differences. For instance in the latest example, if you invoke a storage command like 'accMgr.storeUser ( user )', the stored entity, user, is automatically changed when the underline access mean is the relational back end (e.g., if it is an existing user, existing data are merged with the parameter, where this is missing such data), while the user object is not touched when the web service infrastructure is used under the hood. This is to keep things simple and fast. In order to write safe code, we suggest to assume the parameters to myEquivalents system are never changed, unless otherwise specified.