Usage

This section provides generic usage information and usage information per Java EE application server.

The Ethereum RAR can be deployed separately, or embedded within your EAR.

Embedded RAR

Within your EAR, you need to include the RAR.

If you use Maven, refer to the e-contract.be Maven repository via:

<repository>
    <id>e-contract</id>
    <url>https://www.e-contract.be/maven2/</url>
    <releases>
        <enabled>true</enabled>
    </releases>
</repository>

Include the resource adapter RAR within your Java EE application EAR via:

<dependency>
    <groupId>be.e-contract.ethereum-resource-adapter</groupId>
    <artifactId>ethereum-rar</artifactId>
    <version>1.4.0</version>
    <type>rar</type>
</dependency>

Within your maven-ear-plugin configuration, under modules, you put the following:

<rarModule>
    <groupId>be.e-contract.ethereum-resource-adapter</groupId>
    <artifactId>ethereum-rar</artifactId>
    <bundleFileName>ethereum-ra.rar</bundleFileName>
</rarModule>

Within your EJB JAR or WAR you can now add the API dependency under dependencies via:

<dependency>
    <groupId>be.e-contract.ethereum-resource-adapter</groupId>
    <artifactId>ethereum-ra-api</artifactId>
    <version>1.4.0</version>
    <scope>provided</scope>
</dependency>

JBoss EAP/WildFly

The EthereumConnectionFactory is available within JNDI under:

java:/EthereumConnectionFactory

Hence you can refer to it via:

@Resource(mappedName = "java:/EthereumConnectionFactory")
private EthereumConnectionFactory ethereumConnectionFactory;

or in an application server independent way via:

@Resource(name = "EthereumConnectionFactory")
private EthereumConnectionFactory ethereumConnectionFactory;

where you provide within your META-INF/jboss-ejb3.xml to following mapping:

<jboss:enterprise-beans>
    <session>
        <ejb-name>YourBeanNameHere</ejb-name>
        <resource-ref>
            <res-ref-name>EthereumConnectionFactory</res-ref-name>
            <jndi-name>java:/EthereumConnectionFactory</jndi-name>
        </resource-ref>
    </session>
</jboss:enterprise-beans>

For usage of the EthereumMessageListener you need to refer to the resource adapter explicitly. Do this by adding the following to your META-INF/jboss-ejb3.xml:

<assembly-descriptor>
    <mdb:resource-adapter-binding>
        <ejb-name>YourEthereumMDB</ejb-name>
        <mdb:resource-adapter-name>#ethereum-ra.rar</mdb:resource-adapter-name>
    </mdb:resource-adapter-binding>
</assembly-descriptor>

Or via a JBoss specific annotation on the MDB class:

import org.jboss.ejb3.annotation.ResourceAdapter;

@ResourceAdapter("#ethereum-ra.rar")

Oracle WebLogic

The EthereumConnectionFactory is available within JNDI under:

EthereumConnectionFactory

So you can refer to it via:

@Resource(name = "EthereumConnectionFactory")
private EthereumConnectionFactory ethereumConnectionFactory;

where you provide within your META-INF/weblogic-ejb-jar.xml to following mapping:

<weblogic-enterprise-bean>
    <ejb-name>YourBeanNameHere</ejb-name>
    <resource-description>
        <res-ref-name>EthereumConnectionFactory</res-ref-name>
        <jndi-name>EthereumConnectionFactory</jndi-name>
    </resource-description>
</weblogic-enterprise-bean>

For usage of the EthereumMessageListener you need to refer to the resource adapter explicitly. Do this by adding the following to your META-INF/weblogic-ejb-jar.xml:

<weblogic-enterprise-bean>
    <ejb-name>YourEthereumMDB</ejb-name>
    <message-driven-descriptor>
        <resource-adapter-jndi-name>EthereumResourceAdapter</resource-adapter-jndi-name>
    </message-driven-descriptor>
</weblogic-enterprise-bean>

Deployed RAR

The advantages of having a deployed RAR instead of an embedded RAR are:

multiple applications can use the same resource adapter
you can reconfigure the resource adapter more easily within the application server

When deploying the RAR, make sure to give it a versionless name like ethereum-ra.rar. This makes it easier to refer to it from within your Java EE applications.

JBoss EAP/WildFly

Within your EAR you need to include META-INF/jboss-deployment-structure.xml with:

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="deployment.ethereum-ra.rar" export="true"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Further usage instructions are the same as for the embedded RAR case, except we change the RAR name from the embedded name #ethereum-ra.rar to ethereum-ra.rar of course.

If you want to be able to reconfigure the Ethereum resource adapter within the application server itself, you need to remove META-INF/ironjacamar.xml from the ethereum-ra.rar. Next deploy ethereum-ra.rar and configure standalone-full.xml under urn:jboss:domain:resource-adapters:6.0 as follows:

<subsystem xmlns="urn:jboss:domain:resource-adapters:6.0">
    <resource-adapters>
        <resource-adapter id="ethereum-ra.rar">
            <archive>
                ethereum-ra.rar
            </archive>
            <transaction-support>XATransaction</transaction-support>
            <config-property name="nodeLocation">http://localhost:8545</config-property>
            <config-property name="webSocketNodeLocation">ws://localhost:8546</config-property>
            <connection-definitions>
                <connection-definition class-name="be.e_contract.ethereum.ra.EthereumManagedConnectionFactory"
                                       jndi-name="java:/EthereumConnectionFactory"
                                       pool-name="EthereumConnectionFactory">
                    <xa-pool>
                        <min-pool-size>5</min-pool-size>
                        <max-pool-size>50</max-pool-size>
                    </xa-pool>
                    <timeout>
                        <allocation-retry>5</allocation-retry>
                        <allocation-retry-wait-millis>5000</allocation-retry-wait-millis>
                    </timeout>
                    <recovery>
                        <recover-credential>
                            <user-name>crashrec</user-name>
                            <password>crashrec</password>
                        </recover-credential>
                    </recovery>
                </connection-definition>
            </connection-definitions>
            <admin-objects>
                <admin-object class-name="be.e_contract.ethereum.ra.EthereumAdminImpl" jndi-name="java:/EthereumAdmin">
                </admin-object>
            </admin-objects>
        </resource-adapter>
    </resource-adapters>
</subsystem>

Change the Ethereum client node location configuration at runtime as follows:

./jboss-cli.sh
connect
ls /subsystem=resource-adapters/resource-adapter=ethereum-ra.rar/config-properties=nodeLocation
/subsystem=resource-adapters/resource-adapter=ethereum-ra.rar/config-properties=nodeLocation:write-attribute(name=value,value=http://localhost:8545)
ls /subsystem=resource-adapters/resource-adapter=ethereum-ra.rar/config-properties=webSocketNodeLocation
/subsystem=resource-adapters/resource-adapter=ethereum-ra.rar/config-properties=webSocketNodeLocation:write-attribute(name=value,value=ws://localhost:8546)
:reload