{anchor:how-to-easybpel-extended-activity}

The [WS-BPEL 2.0 standard|http://docs.oasis-open.org/wsbpel/2.0/Primer/wsbpel-v2.0-Primer.pdf] provides the possibility to add activities for specific usage. These extensions can be formalized in a BPEL process with the following mechanism:

We define an extension as following:
{code:xml}
<bpel:extensions>
<bpel:extension
namespace="http://easybpel.ebmwebsourcing.com/extension/oneextension"
mustUnderstand="yes">
</bpel:extension>
</bpel:extensions>
{code}
The namespace attribute corresponds to the namespace of the extended activity. The mustUnderstand attribute specifies if the BPEL engine must understand the extended
activity (that is mandatory for the process to be successfully executed) or if it can ignores it (i.e. a debug activity).

Then the extended activity can be placed in the BPEL process, embedded in a {{<bpel:extensionActivity></bpel:extensionActivity>}} couple of tags.


h1. How to implement an extended activity in EasyBPEL?

As EasyBPEL is put upon EasyVIPER, an extended behavior is expected to be developed for each extended activity in EasyBPEL.
First we consider an extended behavior is available (see the specific how-to on EasyVIPER page (TODO link to easyviper how to)).

The following figure shows this principle of EasyBPEL activity mapped into an EasyVIPER behaviour. For the *Invoke* activity defined in the BPEL specification, a corresponding *Send* behavior has been implemented in EasyVIPER. In a same way, any extended activity defined at EasyBPEL level corresponds to an extended behavior at EasyVIPER level.

!extended_activity.gif|border=1!

An extended activity implementation must be composed of a JAVA interface extending the {{ExtendedActivity}} interface:

{code:title=MyExtendedActivity.java|borderStyle=solid}
import com.ebmwebsourcing.easybpel.model.bpel.api.activity.extension.ExtendedActivity;


public interface MyExtendedActivity extends ExtendedActivity {

//Some specific stuff related to MyExtendedActivity

}
{code}

A JAVA class must implement this {{MyExtendedActivity}} interface:

{code:title=MyExtendedActivityImpl.java|borderStyle=solid}
...
import mypackage.MyExtendedActivity;
...

@org.oasisopen.sca.annotation.Scope("COMPOSITE")
@org.oasisopen.sca.annotation.Service(value=MyExtendedActivity.class,names="service")
@PolicySets("frascati:scaEasyPrimitive")
public class MyExtendedActivityImpl extends DebugPackageExtendedActivityImpl<TMyExtendedActivity> implements MyExtendedActivity {

public MyExtendedActivityImpl(QName tag, Element elmt, ExtensionActivity parent)
throws BPELException {
super(tag, elmt, parent);
//Some specific stuff related to MyExtendedActivityImpl
}

@Override
public void validate(BPELStaticAnalysis analyzer) {
//Some specific stuff related to MyExtendedActivityImpl
}

@Override
public Node generate(Scope scope) throws CoreException {
//Some specific stuff related to MyExtendedActivityImpl
}

@Override
protected TMyExtendedActivity convertElementToModel(Element elmt)
throws BPELException {
TMyExtendedActivity res = null;
try {
JAXBElement<TMyExtendedActivity> jaxb = this.getJaxbContext().createUnmarshaller().unmarshal(elmt, TMyExtendedActivity.class);
res = jaxb.getValue();
} catch (JAXBException e) {
throw new BPELException(e);
} catch(SchemaException e){
throw new BPELException(e);
}
return res;
}

}
{code}

You have to fill the constructor (at least with a {{super()}} method), the {{convertElementToModel()}}, {{validate()}} and {{generate()}} methods.
The {{validate}} method SHOULD be filled whereas the {{generate}} method MUST be filled. It consists basically in instantiating the extended behavior developed at EasyVIPER level. Here is an example of {{generate}} method:
{code:title=MyExtendedActivityImpl.java excerpt|borderStyle=solid}
@Override
public Node generate(Scope scope) throws CoreException {

MyExtendedBehavior myExtendedBehavior = new MyExtendedBehaviorImpl();
// myExtendedBehavior.foo()
Node behaviourNode = scope.createNode(this.model.getName(), myExtendedBehavior);
return behaviourNode;
}
{code}


Your extended activity is completed. You only needs to add it in dependency of your BPEL engine and to set or create an ExtendedActivityInitialization.xml file
{code:xml|title=ExtendedActivityInitialization.xml|borderStyle=solid}
<?xml version="1.0" encoding="UTF-8"?>

<tns:ExtendedActivitiesInitialization
xmlns:tns="http://com.ebmwebsourcing.easybpel/ExtendedActivityInitialization"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://com.ebmwebsourcing.easybpel/ExtendedActivityInitialization
../../main/resources/ExtendedActivityInitialization.xsd ">
<tns:extendedActivityInitialization>
<tns:definition>MyExtendedActivityPackageConfiguration.xml</tns:definition>
<tns:implementation>mypackage.MyExtendedActivityImpl-....jar</tns:implementation>
</tns:extendedActivityInitialization>
</tns:ExtendedActivitiesInitialization>
{code}