JCA for SSH and sFTP

JCA for SSH

JCA for SSH is powerful connector, yet simple to use to connect to legacy or remote systems via SSH. It also provides the functionality to upload and downloads file using sFTP.

This release support the outbound only. The future release will contain the inflow or inbound functionality that will receive messages from legacy systems.

JCA for SSH News

Release 0.0.1 Now available!

About JCA for SSH

JCA for SSH is powerful connector, yet simple to use to connect to legacy or remote systems via SSH. It also provides the functionality to upload and downloads file using sFTP.

JCA for SSH not only provide the SSH functionality, it also provide the sFTP functionality on the same connection.

JCA for SSH is used in J2EE environment when connecting from container components such as EJBs, servlet to an EIS systems. More Information can be found at: JCA Overview

The following picture extracted from the SUN web depicts JCA architecture:

The picture below shows the different components that can be inserted into the architecture. JCA for SSH makes sure that the connection pool is maintained and reconnects automatically in case of connection failure or disconnect from the remote host.

JCA Overview

The Enterprise Architecture Integration (EAI) provides a common framework for integrating incompatible systems running on different platforms. Many legacy applications and custom databases are still being used and run well that there is no need for a change. The aim of EAI is to reduce the complexity and improve reliability scalability and flexibility.
One of the restrictions on EJB and IOs in general. An EJB should not manage a file descriptors (Sockets or Files). The communication with EIS is done through Sockets. Sockets are the standard low level communication primitives that appeared in early 1970's for Unix systems. The Sockets are not serializable therefore, EJB cannot passivate.
In distributed environment, EJB are distributed at runtime running on separate JVM or machines. More information about EJB restrictions may be found at EJB Restrictions.
But EJB should find a way to communicate with databases and other EIS system. JCA provides the solution where the JCA handles the low level connections with EIS and return a Handle for the connection to the J2EE middle tier components.
Before we start the implementation of a Resource Adapter to provide SSH and Secure FTP functionalities to the EJB, let's list the main JCA components:
* System contracts
* Client API
* Resource adapter module

System contracts
System contracts define the connection between the application server and the EIS. The EIS side of the system contract is implemented by a resource adapter -- a system-level software driver specific to the EIS. The application server and the resource adapter collaborate by means of the system contract to provide secure, robust, scalable access to the EIS.
Three types of system contracts are defined: The connection management contract enables physical connections to the EIS and provides a mechanism for the application server to pool those connections.
The transaction management contract supports access to an EIS in a transactional context. Transactions can be managed by the application server, providing transactions that incorporate other resources besides the EIS, or they can be internal to the EIS resource manager, in which case no transaction manager is required.

The security contract supports secure access to the EIS. How system contracts are implemented on each side (application server and resource adapter) is not specified by JCA; they can be implemented as each vendor sees fit.

Client API
The second element of JCA is the client API. The API can be specific to the resource adapter or it can be the standard Common Client Interface (CCI) as defined by JCA. The CCI is meant to be used by vendors to provide integration tools and frameworks, making it easier for developers to access enterprise systems. It is recommended (but not mandated) that the resource adapter make use of the CCI.
Resource adapter module
The resource adapter module contains all of the elements necessary to provide EIS connectivity to applications. Specifically, the resource adapter module includes the following components:
- The Java classes and interfaces that implement the resource adapter
- Any utility Java classes required by the resource adapter
- Any EIS-specific platform-dependent native libraries
- The deployment descriptor
Application servers make use of the deployment descriptor supplied with a resource adapter to configure it to a specific operational environment.

Handling of Connections
An application component accesses the resource adapter through ConnectionFactory and Connection interfaces, which are provided by the resource adapter implementer. These interfaces can be CCI interfaces (javax.resource.cci.ConnectionFactory and javax.resource.cci.Connection) or they can be specific to the resource adapter. The classes that implement these interfaces are also provided with the resource adapter. The connection factory is obtained through the Java Naming and Directory Interface (JNDI) so that the application need have no knowledge of the underlying implementation class. Once the connection factory is retrieved, a connection is obtained from the connection factory through the getConnection() method. At least one getConnection() method must be provided by the connection factory, though more may be provided. It is important to note that a Connection is an application-level handle to an underlying physical connection to the EIS, represented by a ManagedConnection. Once the application component is finished with the connection, it calls the close() method on the connection. A resource adapter is required to provide a method on the connection to close the connection. This method must delegate the close to the ManagedConnect ion that created the connection handle. Closing a connection handle should not close the physical connection to the EIS.

Managing Connections
The getConnection() method in the connection factory does not actually create a connection;
it calls the allocateConnection() method on its associated ConnectionManager.
The ConnectionManager interface is implemented by the application server.
It is associated with a connection factory in an implementation-specific manner when the connection factory is instantiated. The call to the ConnectionManager allows the application server to "hook in" to the resource adapter functionality to provide pooling, transaction, and security services. A ConnectionRequestInfo object may be passed to allocateConnection() to pass connection request-specific information.
The ConnectionManager, in turn, calls on a ManagedConnection to obtain the connection handle. The connection handle is passed back through the ConnectionManager to the connection factory and on to the application component.

Connection Pooling
The resource adapter provides a class that implements the ManagedConnectionFactory interface. The ManagedConnectionFactory class acts as a factory for both connection factory instances and ManagedConnection instances. When the application server needs to create a connection factory, it calls the createConnectionFactory() method, passing in an instance of ConnectionManager; this is the instance that is called when the application component calls getConnection() on the connection factory, as discussed previously.

The application server uses one of two ManagedConnectionFactory methods to create or request managed connections. When the server requires a new instance of ManagedConnection, it calls the createManagedConnection() method. When the server wants to re-use an existing ManagedConnection, it calls the matchManagedConnections() method. To find the right match, the server passes in a set of ManagedConnections that could possibly meet the criteria of the requested connection, along with information about the desired connection type. Internally, the matchManagedConnection() method compares this information with the candidate set to determine if a match can be made. If so, it returns the matching ManagedConnection; if not, it returns null.

So far we have talked about the outbound. JCA also supports the inflow and is implemented using ActivationSpec and Inbound Message Driven Bean. The inbound is not implemented in this release.

Dependencies

JCA-for-SSH uses an SSHTools Open source component in the backend. you can download the full Sshtools version from :
SSH Tools . The JCA-for-SSH comes with j2ssh-common.jar and j2ssh-core.jar .

JCA for SSH is built on JBoss, but can run on any other container.
The following jar are required:

common-loggings.jar
j2ee.jar
log4j.jar

Using JCA for SSH

We will be using JBoss for this guide. Install

Unzip JCA-FOR-SSH-x.x.x.zip and deploy it into JBoss or any other container. The .rar file contains the JCA adapter and the .war file contain the test servlet.

Define the DataSource

We need to define our Datasource, in order to do so, we create an XML descriptor of the datasource. Below is the description of the datasource.

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE
	 connection-factories PUBLIC "-//JBoss//DTD JBOSS JCA Config 1.5//EN"
	 "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd">
<connection-factories>

	 <no-tx-connection-factory>
	 
	    <jndi-name>ra/jca-test</jndi-name>
			<rar-name>ssh-pool-1.0.0.rar</rar-name>
			<connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
			<config-property name="hostname"
			type="java.lang.String">localhost</config-property>
			<config-property name="username"
			type="java.lang.String">user</config-property>
			<config-property name="password"
			type="java.lang.String">password</config-property>
			<min-pool-size>3</min-pool-size>
			<max-pool-size>10</max-pool-size>
			
	 </no-tx-connection-factory>
	
</connection-factories>

The JNDI_NAME is set to ra/jca-test.
we are using CCI (Common Client Interface) as Connection Factory.
We specify the hostname and the credentials.
min-pool-size specifies the minimum number of connection that shall be maintained by the container's ConnectionManager.
max-pool-size specifies the maximum number of connection for this connector.

Save this file into jca-test-ds.xml.

Code

private Context getInitialContext() throws NamingException

    {
	   Hashtable props = new Hashtable();
	   String providerUrl = "";

	   props.put(Context.INITIAL_CONTEXT_FACTORY,
		   "org.jnp.interfaces.NamingContextFactory");
	   props.put(Context.URL_PKG_PREFIXES,
		   "org.jboss.naming:org.jnp.interfaces");
	   props.put(Context.PROVIDER_URL,"jnp://localhost:1099");
	   Context ctx = new InitialContext(props);
	   return ctx;
    }
	




//Get the Initial Context
Context context = getInitialContext();
Object obj  = context.lookup("java:ra/jca-test");
// get the Connection Factory
ConnectionFactory connectionFactory = (ConnectionFactory)obj;
// Get a connection
Connection connection = connectionFactory.getConnection();

For SSH, we have choosen to use the CCI Interaction class.

//Create an Interaction
Interaction interaction = connection.createInteraction();
//Create an Interaction Record Factory
RecordFactory recordFactory = connectionFactory.getRecordFactory();
//Create the Record that will contain the command
MappedRecord mappedRecord = recordFactory.createMappedRecord("dir > /tmp/Test.txt");
//Execute the command on the legacy system
Record resultRecord = interaction.execute(null, mappedRecord);
// If you are expecting result back.
System.out.println("Result: " + resultRecord.getRecordName());

For SFTP, we have defined our own interface that inherits from CCI connection.

IEisConnection eisConn = (IEisConnection) connection;
//We will ftp over the file create by the previous command.


String remoteFile = "/tmp/Test.txt";
String toLocal = "C:\\Test.txt";
eisConn.get(toLocal, remoteFile);
eisConn.close();

Getting JCA for SSH

User's Guide

Release Notes