Contributors Frequently Asked Questions

Developing adaptors

  1. What are the pre-requisites for building JSAGA adaptors ?
  2. How to create a new adaptor for JSAGA ?
  3. How to modify an existing adaptor for JSAGA ?
  4. How to print Web service messages to a local file ?
  5. How to push my contribution to GIT ?
  6. How to import the maven project into Eclipse (http://www.eclipse.org/) ?

Testing adaptors

  1. How to run integration tests ?
  2. How to configure test-suite ?
  3. How to create files and directories for data test suite ?

Developing adaptors

What are the pre-requisites for building JSAGA adaptors ?

[top]

How to create a new adaptor for JSAGA ?
  • Install JSAGA Archetype 1.0 (or later) 
    mvn install:install-file -DgroupId=org.apache.maven.archetypes \
-DartifactId=maven-archetype-jsaga -Dversion=1.0 -Dpackaging=jar \
-Dfile=maven-archetype-jsaga-1.0.jar
  • Create the skeleton of your project 
    mvn archetype:generate -DarchetypeArtifactId=maven-archetype-jsaga
  • Replace all occurences of CHANGE in file pom.xml
  • Rename and modify the class MyProtocolDataAdaptor (see "Contributors Guide").
  • Build your adaptor 
    mvn test

[top]

How to modify an existing adaptor for JSAGA ?
  • Download and extract the latest version of the adaptor from here.
  • Modify the code.
  • Run the non-regression test-suite.
  • Generate a patch (WARNING: no slash at the end of directory name) 
    diff -Naur -xbuild <origin> <modified>
  • Send it to JSAGA developers for inclusion in future JSAGA releases.

[top]

How to print Web service messages to a local file ?
Add the following lines 
log4j.rootLogger=DEBUG, A1

log4j.logger.org.apache.axis.transport.http.HTTPSender=DEBUG
log4j.appender.A1=org.apache.log4j.FileAppender
log4j.appender.A1.File=/tmp/ws.log
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x  %m%n
to the LOG4J configuration file 
etc/log4j.properties
This will printout all web service messages into /tmp/ws.log. You can use another Appender.

[top]

How to push my contribution to GIT ?
First, request for access to the jsaga-contrib repository and configure your SSH client (see CC-IN2P3 VCS guide). 
# initialization
git clone git://git.in2p3.fr/jsaga
cd jsaga
git remote add jsaga-contrib ssh://git.in2p3.fr/jsaga-contrib

# list existing branches
git ls-remote ssh://git.in2p3.fr/jsaga-contrib

# create your own branch
git checkout -b myBranch
# modify your code
...
# commit your modifications
git commit ...
# push your commits to your remote branch in the jsaga-contrib repository
git push jsaga-contrib HEAD:myBranch

[top]

How to import the maven project into Eclipse (http://www.eclipse.org/) ?
Either generate Eclipse project from maven CLI:
  • Set the Eclipse "Classpath Variable" M2_REPO to the path of your maven local repository.
  • mvn install
mvn -s profiles.xml eclipse:eclipse
  • File / import existing projects into workspace and select the jsaga directory.
  • (for more information see: http://maven.apache.org/guides/mini/guide-ide-eclipse.html http://laurent.granie.free.fr/index.php?2006/12/13/25-maven2-et-eclipse)
Or install and use the plugin Q (http://code.google.com/p/q4e/)

[top]

Testing adaptors

How to run integration tests ?
  • From your build environment:

    Most adaptors allow for listing available tests:

    ls test/src/integration/
mvn integration-test -Dtest={integration.MyProtocolIntegrationTestSuite}\$index

    To run {SubTest1} only, enter:

    mvn integration-test -Dtest={integration.MyProtocolIntegrationTestSuite\$SubTest1}

    Errors are logged into build/surefire-reports/{integration.MyProtocolIntegrationTestSuite$SubTest1}.txt

    Note: On Unix-like operating systems, the '$' must be escaped ('\$').

  • From an installation of JSAGA:

    To run {MyProtocolIntegrationTestSuite}, enter:

    junit-run-test {integration.MyProtocolIntegrationTestSuite}

    Errors are displayed on console.

[top]

How to configure test-suite ?
There are 4 configuration files:
  • test/resources/etc/jsaga-config.properties: is not used by test-suite (used when testing your configuration with JSAGA CLIs).
  • test/resources/etc/jsaga-default-contexts.xml: configures your adaptor and its security context.
  • test/resources/etc/log4j.properties: configures log severity thresholds for test-suite.
  • test/resources/saga-test.properties: configures the test-suite (i.e. URLs and test parameters).
Content of file saga-test.properties depends on the type of adaptor:
  • For a security adaptor: 
    # can be empty
  • For a data adaptor: 
    myprotocol.base.url=uri://...
myprotocol.base2.url=uri://...
test.base.url=test://emulator.test.org:1234/
  • For a job adaptor: 
    myprotocol.jobservice.url=uri://...
# optional test parameters:
myprotocol.finalyTimeout=...
myprotocol.maxQueuingTime=...
myprotocol.candidate.host=...

[top]

How to create files and directories for data test suite ?
mkdir -p dir/subdir ; echo "Content of file 1..." > dir/subdir/file1.txt
mkdir -p dir2/subdir ; echo "Content of file 2 on base2.url..." > dir2/subdir/file2.txt

[top]