Plugin Developers Guide

Setting environment

Recommendations

2. Parameter declaration
3. Parameter value

Choosing the right interface

2. Interfaces available to all plugins
3. Interfaces available to connector plugins only

Testing your plugin

2. All plugins except connector
3. Connector plugin

Using your plugin

Setting environment

1. Download and install a Java Development Kit (JDK)
2. Download and install Apache Maven
3. Download and install the maven archetype files ( maven-archetype-lavoisier-2.1.1.jar and maven-archetype-lavoisier-2.1.1.pom)

   mvn install:install-file -Dfile=maven-archetype-lavoisier-2.1.1.jar -DpomFile=maven-archetype-lavoisier-2.1.1.pom -Dpackaging=jar

4. Create your module:

   mvn archetype:generate -DarchetypeArtifactId=maven-archetype-lavoisier -DarchetypeVersion=2.1.1

Answer to the questions asked by maven:

• groupId: package name (e.g. org.my_company.project)
• artifactId: module name (e.g. lavoisier-adaptor-mytechno)
• version and package: accept default value

Recommendations

Please follow those recommendations to get your plugin easier to maintain by other developers.

---

Parameter declaration

• use private static final constant with name prefixed by P_
• create your Parameter object using static methods of Parameter class.

Reading the Example connector code you will see a simple example :

private static final Parameter<Xml> P_CONTENT = Parameter.xml("content", "Input XML data");
public Parameter[] getUsage() {
    return new Parameter[]{P_CONTENT};
}
               

NB: Enumeration parameter is the only specific case requiring the use of ParameterEnumeration constructor instead of static method of Parameter class. You can start with this example: Log processor code

---

Parameter value

Please use getValue() method to retrieve parameter value :

Xml content = P_CONTENT.getValue(configuration);

Choosing the right interface

First you have to choose the adaptor type (connector, serializer, processor, renderer...): read the Administrator documentation Then you have to choose the adaptor interface that matches your needs (APIs, skills, project context).

---

Interfaces available to all plugins

XML stream interfaces: both enable sequential access only but use very little memory

• SAX-based interfaces rely on SAX API
• XMLEvent interfaces are more high level (less method to implement, context management, ...)

Object Model interfaces: both enable random access by recording the whole tree structure in memory

• DOM-based interfaces rely on DOM standard (more standard)
• DOM4J-based interfaces rely on DOM4J (more efficient)

---

Interfaces available to connector plugins only

Java bean based interfaces: enable random access for XML for fixed schema

• JAXB-based interfaces rely on JAXB API

Byte stream based interfaces: enable sequential access only but allow non XML data

• Input stream based interface
• Output stream based interface

NB: If your legacy API provides both, prefer InputStream which will prevent Lavoisier from having to pipe it.

Testing your plugin

Lavoisier plugin artifact is providing a test environment based on JUnit. To perform functional test we recommend the use of provided TestableChain helper. Obviously you can complete your tests with JUnit traditional usage.

---

All plugins except connector

Use following constructor passing the path of xml input file as parameter.

TestableChain chain = new TestableChain(new ExampleAdaptor(), "/input.xml");
assertEquals(Expected.getAsString("expected/ExampleAdaptor.xml"), chain.getAsString())
               

---

Connector plugin

Use constructor dedicated to connector plugin (without XML input)

• Fully automated

  TestableChain chain = new TestableChain(new ExampleConnector());
  assertEquals(Expected.getAsString("expected/ExampleConnector.xml"), chain.getAsString())
                         

• Semi automated: When the input data is not fixed, you can still automate the execution of the test, but the generated data has to be verified manually. To do so replace the assertion with a dump :

  TestableChain chain = new TestableChain(new ExampleConnector());
  chain.dump(System.out);
                         

• Manual: When the test is requiring specific environment or security context, you have to disable automatic execution of the test by adding '_' (underscore) at the end of file name otherwise the build may fail.

Using your plugin

Build your module ("mvn package') and copy it to 'lib/' directories, in order to be able to use your plugin from your Lavoisier instance.

Notes:

• currently, libraries have to be copied into both 'lib/' and 'jsw/lavoisier/lib' directories.
• currently, home-made plugins used in the Lavoisier configuration file must be referenced with their full class name (i.e. including the namespace).