CoordinatorClient Guide For Developer

Content

Introduction
Function
API
1. Pipeline API
2. Client JavaDoc (API)
HTTPS Communication

Introduction

CoordinatorClient is a client develop library, and it make it possible to use the pipeline service from any application.

JDK, Class

To run at the client side, it's necessary to prepare the environment which is JRE 1.5 or later. The essential library is

coordinatorclient.jar

Please run it through a classpath in the library.

Client method list

You can do the below operations at a client side. Please refer to JavaDoc for more details.

jar files

They are in the API kit. Please unzip the asteria-client-coordinatorclient-0.0.3.zip to get Jar files.

apikit-0.0.3.zip
    /coordinatorclient
       asteria-client-coordinatorclient-0.0.3.zip

Functions

Client

CoordinatorClient is a client class for communicating with the pipeline service. You can do many operations by creating the class and accessing to it.

// The client side connected to host：localhost , port： 25080
CoordinatorClient client = new CoordinatorClient() ;

// The client side connected to host：localhost and the specified port.
client = new CoordinatorClient( 25080 ) ;

// The client side connected to the specified host, port ：25080
client = new CoordinatorClient( "192.168.5.99" ) ;

// The client side connected to the specified host and port.
client = new CoordinatorClient( "192.168.5.99" , 25080 ) ;

// The client side connected to the specified host and port by https.
client = new CoordinatorClient( "https" , "192.168.5.99" , 25081 ) ;

Operation list

The list shows the functions that can be operated at the client side.

Function name	Method
Refer to pipeline list	getPipelineList()
Run pipeline	executePipeline()
Start pipeline	resumePipeline()
Stop pipeline	suspendPipeline()
Import pipeline	importPipeline()
Export pipeline	exportPipeline()
Clear pipeline action cache	clearPipelineCache()
Refer to request list	getRequestList()
Refer to requst details	getRequestDetail()
Retry request	retryRequest()
Cancel request	cancelRequest()
Refer to System DB	selectSystemDB()
Refer to Status DB	selectStatusDB()
Refer to Action DB	selectActionDB()
Clear Action DB Table	deleteActionTable()
Drop Action DB Table	dropActionTable()

Proxy

Set proxy in setProxy().
The sample is as below.

package sample.client;

import java.util.List;

import java.net.Proxy ;
import java.net.SocketAddress ;
import java.net.InetSocketAddress ;

import com.infoteria.asteria.warp.mc.client.CoordinatorClient;
import com.infoteria.asteria.warp.mc.client.PipelineInfo;
import com.infoteria.asteria.net.http.speaker.client.ClientException;

public class Sample01 {
	public static void main( String[] args ) {
		try {
			String pass = "" ;
			CoordinatorClient client = new CoordinatorClient() ;

			int port = proxy port number ;
			SocketAddress addr = new InetSocketAddress( "your Proxy Server" , port ) ;
			Proxy proxy = new Proxy( Proxy.Type.HTTP , addr ) ;
			client.setProxy( proxy ) ;

			client.login( pass ) ;
			List lst = client.getPipelineList(null);
			for ( PipelineInfo pi : lst ) {
				System.out.println( pi ) ;
			}
		} catch ( Exception e ) {
			e.printStackTrace() ;
		}
	}
}

API

Here are pipeline API's link and client JavaDoc's link.

HTTPS Communication

It's necessary to create a key store and set to HTTPS in the server side for the HTTPS communication.

Set server

Steps

Create ant's project file
Create a key store
Edit the configuration files of the server.

Create a key store

Create cert.xml as below under [install_dir]/pipeline/

<project name="keystore" default="dist-keystore" basedir="." >

	<property name="install.path.dir" value="${basedir}" />
	<property name="install.path.cert" value="self.keystore" />
	<property name="keystore.file" value="${install.path.dir}/data/keystore/${install.path.cert}" />
	<property name="keystore.type" value="PKCS12" />

	<property name="key.alias" value="my-group" />
	<property name="cert.password" value="password" />
	<property name="print.cert.password" value="password" />
	<property name="validity.day" value="7400" />

	<path id="anttask.lib.path">
		<fileset dir="${install.path.dir}/lib">
			<include name="asutil.jar"/>
		</fileset>
		<fileset dir="${install.path.dir}/../common/">
			<include name="lib/aac.jar"/>
			<include name="lib/ascert.jar"/>
			<include name="ext/mail.jar"/>
			<include name="ext/iaik_jce_full.jar"/>
		</fileset>
	</path>

	<taskdef name="certcreate" classname="com.infoteria.asteria.security.cert.anttask.CreateSelfSignCertificate" classpathref="anttask.lib.path" />
	<taskdef name="certpassword" classname="com.infoteria.asteria.security.cert.anttask.PasswordEncrypt" classpathref="anttask.lib.path" />

	<target name="selfsigncert">
		<mkdir dir="${install.path.dir}/data/keystore"/>
		<certcreate filename="${keystore.file}" password="${cert.password}" expire="${validity.day}"/>
		<antcall target="printconfig">
			<param name="keystore.type" value="PKCS12" />
		</antcall>
	</target>

	<target name="selfsigncert-keytool">
		<mkdir dir="${install.path.dir}/data/keystore"/>
		<exec executable="keytool">
			<arg line="-genkey -dname "CN=Pipeline , OU=YourCompany, O=com, L=YourCity, S=YourState, C=JP" -alias ${key.alias} -keystore ${keystore.file} -validity ${validity.day} -storepass ${cert.password} -keypass ${cert.password}" />
		</exec>

		<antcall target="printconfig">
			<param name="keystore.type" value="JKS" />
		</antcall>
	</target>

	<target name="selfsigncert-genkey">
		<mkdir dir="${install.path.dir}/data/keystore"/>
		<genkey alias="${key.alias}" storepass="${cert.password}" keystore="${keystore.file}" validity="${validity.day}" >
			<dname>
				<param name="CN" value="Pipeline"/>
				<param name="OU" value="YourCompany"/>
				<param name="O"  value="com"/>
				<param name="L"  value="YourCity"/>
				<param name="S"  value="YourState"/>
				<param name="C"  value="JP"/>
			</dname>
		</genkey>

		<antcall target="printconfig">
			<param name="keystore.type" value="JKS" />
		</antcall>
	</target>

	<target name="printconfig">
		<echo>
<param name="password.encrypted">true</param>
<param name="keystore">true</param>
<param name="keystore.type">${keystore.type}</param>
<param name="keystore.file">data/keystore/self.keystore</param>
<param name="keystore.password">${print.cert.password}</param>
<param name="privatekey.password">${print.cert.password}</param>
		</echo>
	</target>

	<target name="clean">
		<delete file="${keystore.file}" />
	</target>

	<target name="prepare">
		<certpassword property="print.cert.password" password="${cert.password}"/>
	</target>

	<target name="dist-keystore" depends="clean,prepare,selfsigncert" />

	<target name="dist-keystore-keytool" depends="clean,prepare,selfsigncert-keytool" />

	<target name="dist-keystore-genkey" depends="clean,prepare,selfsigncert-genkey" />

</project>

Create a key store by using ant task.

※For more information about keytool, please refer to the website about java products.

// Create by library ：keystore.type will become PKCS12.
$ ant -f cert.xml -Dcert.password=yourpassword dist-keystore

// Create by keytool
$ ant -f cert.xml -Dcert.password=yourpassword dist-keystore-keytool

// Create by GenKey 
$ ant -f cert.xml -Dcert.password=yourpassword dist-keystore-genkey

// Files can be used for [install dir]/pipeline/data/keystore.
// Please run the below command for confirming content.
// If it's created by dist-keystore, please cofirm that java.home/lib/security/java.security's keystore.type=pkcs12.
// Display data
$ keytool -list -keystore data/keystore/self.keystore

Edit configuration files

The below messages can be output after running ant, so please edit [install_dir]/pipeline/conf/pipeline.ifx as below

Set PIPELINE-Coordinator-SSL's enable="on".
Add messages.

If you didn't create it in the dist-keystore, please match the keystore.type with the keystore.type's value in the java.home/lib/security/java.security.
It's better to create a backup for the configuration files when you are editing them.

> Messages about execution result
printconfig:
     [echo]
     [echo] <param name="password.encrypted">true</param>
     [echo] <param name="keystore">true</param>
     [echo] <param name="keystore.type">JKS</param>
     [echo] <param name="keystore.file">data/keystore/self.keystore</param>
     [echo] <param name="keystore.password">GZ7bG/X+EDoxXwL4aG0Nnw==</param>
     [echo] <param name="privatekey.password">GZ7bG/X+EDoxXwL4aG0Nnw==</param>
     [echo]

// Address for editing pipeline.ifx
<process id="PIPELINE-Coordinator-SSL" timeout="300" maxdeadcount="1" enable="on" statistics="true"
	manager="com.infoteria.asteria.warp.task.asframework.PipelineManagerService">
	<accepter pool="1" max="1" class="com.infoteria.asteria.warp.engine.framework.DefaultSSLAccepter">
		<param name="port">25081:TLSv3</param>
		<param name="timeout">180</param>
                         :
		<!-- Add here -->

		<param name="password.encrypted">true</param>
		<param name="keystore">true</param>
		<param name="keystore.type">JKS</param>
		<param name="keystore.file">data/keystore/self.keystore</param>
		<param name="keystore.password">GZ7bG/X+EDoxXwL4aG0Nnw==</param>
		<param name="privatekey.password">GZ7bG/X+EDoxXwL4aG0Nnw==</param>

	</accepter>
	<worker pool="1" max="32" class="com.infoteria.asteria.warp.mc.ashttpd.CoordinatorHttpdWorker">

Confirm

If the login page can be displayed after connecting to https://hostname:25081/, it means that you have completed setting.

Set client

In default, the signature error can be ignored.
Please set javax.net.ssl.HostnameVerifier or javax.net.ssl.SSLSocketFactory for setting Handshake correctly.

setHostnameVerifier()
setSSLSocketFactory()

Please refer to java's API for details.

Execution sample

The execution sample is as below.

■ If you are using CoordinatorClient's default HostnameVerifier and SSLSocketFactory.

package sample.client;

import java.util.List;
import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.SSLSession ;
import javax.net.ssl.SSLContext ;
import javax.net.ssl.SSLSocketFactory ;
import javax.net.ssl.KeyManager ;
import javax.net.ssl.TrustManager ;

import com.infoteria.asteria.warp.mc.client.CoordinatorClient;
import com.infoteria.asteria.warp.mc.client.PipelineInfo;
import com.infoteria.asteria.net.http.speaker.client.ClientException;

public class Sample02 {
        public static void main( String[] args ) {
                try {
                        String pass = "" ;
                        CoordinatorClient client = new CoordinatorClient( "https" , "localhost" , 25081 ) ;

                        // Set HostnameVerifier
                        // HostnameVerifier verifier = do some thing 
                        // client.setHostnameVerifer( verifier ) ;

                        // Set SSLSocketFactory
                        // KeyManager[] km = do some thing ;
                        // TrustManager[] tm = do some thing ;
                        // SSLContext sslcontext= SSLContext.getInstance("SSL");
                        // sslcontext.init(km, tm, new SecureRandom());
                        // client.setSSLSocketFactory( sslcontext.getSocketFactory() ) ;

                        client.login( pass ) ;

                        List<PipelineInfo> lst = client.getPipelineList(null);
                        for ( PipelineInfo pi : lst ) {
                                System.out.println( pi ) ;
                        }
                } catch ( Exception e ) {
                        e.printStackTrace() ;
                }
        }
}

■ If set the constructor's own HostnameVerifier and SSLSocketFactory

package sample.client;

import java.util.List;
import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.SSLSession ;
import javax.net.ssl.SSLContext ;
import javax.net.ssl.SSLSocketFactory ;
import javax.net.ssl.KeyManager ;
import javax.net.ssl.TrustManager ;

import com.infoteria.asteria.warp.mc.client.CoordinatorClient;
import com.infoteria.asteria.warp.mc.client.PipelineInfo;
import com.infoteria.asteria.net.http.speaker.client.ClientException;
import com.infoteria.asteria.net.http.speaker.client.HttpsInitializable ;

public class Sample03 {
        public static void main( String[] args ) {
                try {
                        String pass = "" ;
                        CoordinatorClient client = new CoordinatorClient( new MyHttpsInitialize()  , "hostname.net" , 25081 ) ;
                        client.login( pass ) ;
                        List<PipelineInfo> lst = client.getPipelineList(null);
                        for ( PipelineInfo pi : lst ) {
                                System.out.println( pi ) ;
                        }
                } catch ( Exception e ) {
                        e.printStackTrace() ;
                }
        }

        // Class for creating HostnameVerifier , SSLSocketFactory
        class MyHttpsInitialize implements HttpsInitializable {

                public boolean useDefaultHostnameVerifier() {
                        return false ;
                }

                public boolean useDefaultSSLSocketFactory() {
	                    return false ;
	            }

                public HostnameVerifier createHostnameVerifier() {
                        // Create HostnameVerifier
                		return new HostnameVerifier() {
                			public boolean verify( String name , SSLSession session ) {
                					return true ;
                			}
                		} ;
                }

                public SSLSocketFactory createSocketFactory() throws java.security.NoSuchAlgorithmException , java.security.KeyManagementException {
                        // Create SSLSocketFactory
                        KeyManager[] km = null;
                        TrustManager[] tm = { new X509TrustManager() {
                                public void checkClientTrusted(X509Certificate[] arg0, String arg1) throws CertificateException { }
                                public void checkServerTrusted(X509Certificate[] arg0, String arg1) throws CertificateException { }
                                public X509Certificate[] getAcceptedIssuers() { return null;}
                                }
                        };
                        SSLContext sslcontext= SSLContext.getInstance("SSL");
                        sslcontext.init(km, tm, new SecureRandom());
                        return sslcontext.getSocketFactory() ;
                }
        }
}

▲ To the top of the page