Soaplab   Frequently Asked Questions

  Questions

  Answers

I am getting OutOfMemoryError

If this error is from the underlying Applab server we recommend using the most recent version of Applab server that fixes major memory leaks in the server. The new applab.jar file replaces the following previous 4 jar files; ApplabServer.jar, AppLabShare.jar, AppLabClient.jar, adaptors.jar. After downloading the applab.jar file to your SOAPLAB_HOME/lib directory, please delete the lines in the run-AppLab-server script that adds the above 4 jar files to the CLASSPATH, and then instead add a new line for adding the applab.jar file to the CLASSPATH.

Memory used by Java programs is assigned when you start JVM - and it does not use automatically the whole memory that is available. If your computer has more memory available you need to say how much memory your Java process can use, by using the -mx option, for example: -mx256m.

Remember, however, that there are usually three Java programs involved:
  • The underlying AppLab server (not applicable for Gowlab-based services). It has -mx256m set by default in run-AppLab-server script.
  • The Tomcat server. If the OutOfMemory happens in Tomcat, this error message is recorded in the catalina.out log file. To set the memory size, use the environment variable CATALINA_OPTS before starting Tomcat. This variable is read by catalina.sh start-up script. For example: export CATALINA_OPTS=-mx256m.
  • And finally, a Soaplab client (if it is written in Java). Add the -mx option to the script that invokes the client, for example to the run-analysis-client.

How to keep results, especially big ones, on the server side

Every result can be configured in a way that the Soaplab server creates it but returns only its URL - and the client can get the result using an ordinary HTTP request. To make this happen, you need to put an additional option in the ACD file in a result definition, for example: 

     outfile: missed  [
        parameter: "Y"
        information: "Genbank entries of disguarded hits"
        comment: make_url
     ]
The only glitch is that the new result (named with the suffix _url) does not appear in the list of available results. So the list, in the example above, shows only result missed, but in fact you can also ask for a result named missed_url.

I have defined a default value in the ACD file but it does not appear on the command line

The default values are meant to be the application defaults, meaning that if they are not sent the application itself uses these default values internally (so having them in the ACD file is more or less for the user information).

However, sometimes you want to send default values. There are at least two reasons for doing that:

  • When you want to have a different default value from the application (e.g. the graphs-making application dot does not produce by default a PNG format but you wish that your web service does).
  • When the application itself does not have any default value (e.g. a HelloWorld web services uses the Unix command echo to produce a text greeting but echo does not have any default message).

In these cases, in the ACD file, you need to add (to a relevant parameter): 

    comment: "defaults"

How to send binary input data

Soaplab/Applab currently does not support sending binary input.

However, current Soaplab/Applab supports data type filelist that actually sends input files as binary files. So if you use filelist you get binary input. See How to send an unknown/unspecified number of input files.

How to send an unknown/unspecified number of input files

If your analysis tool can accept/understand a file where each line represents a name of an input file, use filelist in the ACD file: 

    filelist: templates  [
       ...
    ]
This filelist allows to send as many inputs as you wish, Soaplab server will collect them, put them in a temporary directory and re-create a filelist with items from this temporary directory, and put this new file list on the command line.

An example of such command line would be: 

    your-analysis -templates recreated-filelist
Or, with a slightly different ACD file: 
    filelist: templates  [
       parameter: "Y"
       ...
    ]
the command line would look like: 
    your-analysis recreated-filelist

If your analysis expects something else, write a wrapper script around your analysis. Or, check the source code for few input adaptors that were written for EMBOSS applications (classes are in the package embl.ebi.EmbossServer).

How to access Soaplab services from behind my firewall

Soaplab uses HTTP and if your firewall does not allow it you need to have a proxy server (ask your system people) running somewhere on your side. You need to know its hostname and port number.
Soaplab itself does not do anything magic with the HTTP proxies - you need to set/use them as with any other Java application. Which means that you need to set three Java properties: 

    -Dhttp.proxyHost=<your-proxy-server-name>
    -Dhttp.proxyPort=<your-proxy-server-port>
    -DproxySet=true
The only annoyance is that the Soaplab scripts put all command-line arguments at the end of the line that invokes a Java application, but the properties must be put between java and the class name. So you need to edit the script you are using. For example, in the script run-analysis-client, replace the line: 
    exec java -cp $CLASSPATH AnalysisClient "$@"
with 
    exec java -cp $CLASSPATH -Dhttp.proxyHost=your-host \
                             -Dhttp.proxyPort=your-port \
                             -DproxySet=true \
                             AnalysisClient "$@"
I wish to run more AppLab servers

You may wish to run more AppLab servers in order to put the load on more machines, or to separate production and testing services, for example. There are several options to do it:

The easiest option is to run separate Tomcats for each of these AppLab servers. The only additional item to think about is when more than one AppLab server are running on the same machine. Each such AppLab server needs to use a different port number. The port number is defined in the Server.cfg, by default it is 2425. so do not forget to change there the line: 

       ooc.iiop.port = 2425
to something else.

The disadvantage of this option is that you will have two (or more) different endpoints (URLs) for your services (because you have two or more Tomcats running).

The alternative is to access more than one AppLab server from the same Tomcat (the issues with the AppLab port numbers still applied here). Remember that Soaplab communicates with AppLab servers using IOR files - details are here. It explains that your AppLab-based services can be deployed using either parameter applab_analysis or applab_factory, both containing an IOR file name. Therefore, in order to have more AppLab servers, you need to make sure that these IOR files are differently named.

The only thing you cannot have, however, is to have one list (factory) service that lists services from more than one AppLab server. For example, you can deploy two list services with names such as AppLabFactory and ApplabFactory_testing, both with different sets of services, but you cannot merge them into one list service. Sorry for that...

There is also an archived email from Marc explaining the process in details.

Can a Soaplab service return more than one result

Yes, it can. Here is an example of an ACD file for the UNIX program tee that copies the standard input to the standard output, and additionally it copies the same input also to a file given on its command-line: 

       appl: TwoOutputs [
         documentation: "An example with two outputs"
         groups: "unix"
         nonemboss: "Y"
         executable: "tee"
       ]
       infile: input  [
         additional: "Y"
         parameter: "Y"
         default: "stdin"
       ]
       outfile: result1  [
         additional: "Y"
         default: "stdout"
       ]
       outfile: result2  [
         additional: "Y"
         parameter: "Y"
       ]

Getting an Error: Error in creating XML parser

Occasionally, especially when you run Soaplab the first time in your Tomcat, you may get an error starting with: 

       embl.ebi.utils.GException: ===ERROR===
       Fault details: [ns1:hostname: null]
       Fault string: org.embl.ebi.SoaplabShare.SoaplabException: Internal
                     communication failed. (in cacheMetadata)
                     embl.ebi.AppLabShare.AppLabException: Error in creating XML parser
This is usually due to the XML parser Java classes being put in a wrong place in your Tomcat. Assuming that you have Axis on a default place in your Tomcat (you do not need, but then just correct the paths given below), check:
  • <tomcat-home>/webapps/axis/WEB-INF/lib/ - in this directory should *not* be files xercesImpl.jar nor xmlParserAPIs.jar; if you have them there, move them...
  • ...these files should be in directory <tomcat-home>/common/endorsed (common always exists but you may need to create the endorsed one).
  • Where do you get these xerces files from (if you do not find them in WEB-INF/lib)? For example, in the place where you unpacked Axis, they are in <axis>/lib/.
Restart Tomcat.

Martin Senger
Last modified: Nov 09 2006