[CyberSource logo]


Search documentation:

  Help  Advanced
        Published 05/14/2002 Table of ContentsPreviousNextIndex

Chapter 1

CDK for Java 3.5.0.0

This chapter explains how to develop Java applications to support CyberSource Internet Commerce Suite (ICS) services that use the Simple Commerce Messaging Protocol (SCMP), as presented in the following sections:

Overview

The ICS Java client library distribution includes the library files and application examples. To use the client libraries to go live with your implementation, you must:

System Requirements

You must have root or administrator privileges to use the ICS Java client libraries, along with the following minimum requirements:

Version 3.5.0.0 of CDK for Java was developed and tested with JDK 1.2.2 on the Solaris 2.6 operating system. If you use a JVM that is not developed and supported by Sun Microsystems, you might encounter problems with the ICS CDK for Java.

Installing the ICS Java Client Libraries

To install the ICS Java client libraries, perform the following steps:

  1. Create a target directory.
  2. Uncompress the distribution file you downloaded. For the destination, specify the directory you created in Step 1.
  3. Modify the classpath variable to point to the directory that contains the cdkjava11_3500.jar or cdkjava12_3500.jar file.
  4. For Solaris csh:
    % setenv CLASSPATH \${CLASSPATH}:/your-dir/cdkjava12-3500/cdkjava3500.jar:.:\/usr/Java/lib/classes.zip
    For Solaris sh:
    $ CLASSPATH=\${CLASSPATH}:/your-dir/cdkjava12-3500/cdkjava3500.jar:.:\/usr/Java/lib/classes.zip
    $ export CLASSPATH
    For Windows NT:
    1. Right-click the My Computer icon.
    2. Select Properties.
    3. In the Properties dialog box, select the Environment tab.
    4. Edit the value for classpath to include the directory that contains the cdkjava3500.jar file, adding ;C:. to the end of the path you enter.
    5. Restart the computer.
  5. Run the ECert application to generate your certificate and private key. See "Generating Your Certificate and Private Key" in the ICS2 Developer's Guide, available on the CyberSource Small Business Support Center, for more information.

Testing Your Installation

After installing the ICS Java client libraries and generating your certificate and private key, you are ready to test the installed files.

Testing Your Installation
  1. Ensure that the CDK is properly installed and that the classpath is set (as described in Installing the ICS Java Client Libraries).
  2. Change to the test subdirectory where you installed CDK for Java.
  3. At a shell prompt, enter the following command:
  4. java ICSClientTest
    If the test is successful, the message Transaction succeeded appears.
    If you do not receive the Transaction succeeded message, then contact CyberSource Small Business Customer Support with a full description of:

Test Examples Included in This Version

The ICS Java client library distribution includes several test example files to illustrate the different services that are available. Table 1 provides a listing of these test files and a brief description of what each file demonstrates.

Before you use the example files, you must set your classpath environment variable (as described in Installing the ICS Java Client Libraries). The syntax for using the test files is java test-filename (do not include the .class file extension).

Table 1 ICS Java Client Library Test Example Files  
Test File Name
Description
ICSAuthBillTest.class
Demonstrates how to use the CyberSource Authorization and Billing services.
ICSAuthTest.class
Demonstrates how to use the CyberSource Authorization services.
ICSClientProxyTest.class
Demonstrates the use of a proxy host and proxy port when calling ICS client libraries.
ICSClientTest.class
Provides an example of an implementation that calls the ICS client libraries and requests an application from the ICS servers.
ICSFileTest.class
Provides a mechanism to test various ICS messages. This is a simple application that takes as standard input a file with an ICS message consisting of name=value pairs, then sends the file to the ICS server. This application is for test purposes only, and it is not required by any of the other application files. The syntax for ICSFileTest is
java ICSFileTest message-file
ICSServletTest.class
Provides an example of how to implement servlets. This servlet calls the ICS client libraries and requests an application service.
ICSThreadTest.class
Demonstrates the use of threads in calling ICS client libraries. This class can control the number of loops and threads by passing the numbers as parameters.
SecureRandomTest.class
Tests the secure random number generation, which is very slow on some JVMs.

Each application that is described in Table 1 requires unique, specific fields that must be sent in an ICS request. Refer to the chapters in this guide for information about each function's requirements.

To familiarize yourself with the CDK Java libraries, use the test examples to learn more about CyberSource services. To run the example applications, modify your classpath setting as described in the section "Installing the ICS Java Client Libraries" in the ICS2 Developer Guide, available in the CyberSource Small Business Support Center.

Constructing and Sending SCMP Messages

For information about requesting ICS applications and how your Web site must interact with CyberSource to perform eCommerce transactions, see the chapters "Overview of the Internet Commerce Suite and SCMP" and "Requesting CyberSource ICS Applications" in the ICS2 Developer's Guide, available on the CyberSource Small Business Support Center.

Important  The ics_send function, like the other Java CDK functions, is threadsafe. Do not instantiate a separate ICSClient object for each request. Instantiate the ICSClient object once, then pass that instance into subsequent threads that send SCMP requests.

Proxy support

CyberSource uses the HTTP protocol (by default on port number 80) as its transport mechanism. If your site uses a proxy server, you do not need to modify the http_proxy environment variable; proxy support is already enabled in the SCMP instructions.

CDK for Java uses built-in functions within the JVM client to make HTTP connections. Therefore, CDK for Java uses the standard JVM methods of handling proxies.

To set a regular HTTP proxy, include code in your SCMP request that is similar to the following:

System.getProperties().put("proxySet","true");

System.getProperties().put("proxyHost","proxy.cybersource.com");

System.getProperties().put("proxyPort","80");

To set a SOCKS proxy, include code that is similar to the following:

System.getProperties().put("proxySet","true");

System.getProperties().put("socksProxyHost","socks.cybersource.com");

System.getProperties().put("socksProxyPort","1080");

If you use the Microsoft JVM, include code that is similar to the following:

propSystem.put("firewallSet", "true");

propSystem.put("firewallHost", "your-ProxyServer.com");

propSystem.put("firewallPort", "80");

propSystem.put("http.proxyHost", "your-ProxyServer.com");

propSystem.put("http.proxyPort", "80");

Note  The Microsoft JVM method described above is an untested suggestion. This release of CDK for Java was tested only with the recommended JVM from Sun Microsystems.

CDK for Java uses the URL class to make a socket connection. If you need to specify an HTTP proxy that requires username and password authorization, you must use the ICSClientRequest class. Include code before an ics_send call that is similar to the following:

request.setHTTPProxyUsername("your-username");

request.setHTTPProxyPassword("your-password");

The ICSClientRequest method provides support only for basic proxy authorization. Passwords sent by this method are sent in unencrypted format to the proxy server. For a more secure method of authorization, consider using a SOCKS proxy instead.

Creating an ICSClient() Constructor

To create an ICSClient() constructor, use the following format:

ICSClient(String your-filename)

This constructor format explicitly specifies the properties file name that you enter (your-filename). If you do not specify a properties file name, the ICSClient() constructor searches for a file named ICSClient.props in the properties subdirectory under where you installed your JVM.

The test programs use the preferred ICSClient constructor shown in the format above. A SecureRandomTest program is included to enable you to determine whether or not your JVM is causing problems due to the use of the deprecated SecureRandom number generation.

Handling Application Timeouts

Timeout support is controlled by setting the timeout value in the request:

ICSClientRequest request = new ICSClientRequest();

...

request.setTimeout("90");

The default timeout value is 110 seconds.

Sample Application

The ICSClientTest.java file, included in the CDK for Java software distribution, contains a sample application that calls the ICS client libraries and requests an application from CyberSource.

You can use the ICSFileTest.java file for test purposes. The application takes an SCMP message that consists of fields and name=value pairs, then sends the message to CyberSource. The ICSFileTest.java file allows you to quickly test various SCMP messages.

To send an SCMP test message, enter the following command:

java ICSFileTest input-file

This command takes input-file and sends it to the CyberSource server. You can set any of the parameters as fields.

For more information on SCMP messages and ICS fields, see the ICS2 Developer Guide, available on the CyberSource Small Business Support Center.

Using Java Servlets With CDK for Java

This release of CDK for Java supports servlets. A Java servlet is a server-side applet, as opposed to an applet that runs in a client's browser. The following example shows a servlet that requests and responds to ICS services.

For example, the Order Form Test Servlet demonstrates the use of the ICS2 Java API and performs the following tasks:

For sample code for Java servlets, refer to ICSServletTest.java the included in this download package.

Using Enterprise Java Beans

This release of CDK for Java supports Enterprise Java Beans (EJB), a Java API developed by Sun Microsystems. EJB defines a component architecture for multi-tier client/server systems. This technology enables you to use the pre-built EJBs provided in CDK for Java in your Web site applications.

To use the EJB components provided with CDK for Java, you must have the following software from Sun Microsystems installed on your computer:

CDK for Java provides support for EJBs on EJB-compliant servers. Your server must run one of the following operating systems:

EJB Overview

A typical EJB architecture consists of the following components:

The EJBs that are provided with CDK for Java are stateless session beans.

The following figure provides a graphical representation of the EJB model implemented with CDK for Java.

Figure 1 Overview of CDK for Java EJB Implementation

The EJB container resides on your eCommerce server. When you deploy the EJBs, an EJB Home interface is automatically generated within the container to act as an intermediary for the bean class. An EJB Object interface is also generated within the container for each EJB instance, to implement the business methods of the EJB.

The EJB Home interface identifies the bean class. The interface also creates, finds, and removes bean instances during an EJB client's session. The EJB Object provides access to the business methods contained within the bean, based on the settings in the deployment descriptor.

An EJB client (for example, a Web browser) communicates with the EJB Home interface through the JNDI. The EJB Home implements the life cycle processes for the requested bean. The EJB Object intercepts the method calls and implements transactions, state management, bean persistence, and security services that are passed to it through the EJB Home interface.

When an EJB Object receives and processes a method that contains a call for an ICS service (for example, ics_auth), the EJB Object passes the required field information to the ICS2 servers through SCMP. The ICS2 server sends a reply to the EJB server, and the EJB Object completes the methods appropriate for the reply codes sent by the ICS2 server.

CDK for Java EJB Components

Each project included with CDK for Java contains the following EJB components:

CdkEJBClass

The CdkEJB class defines the methods the client uses to send a transaction to the CyberSource ICS servers. The following methods are defined in the CdkEJB class:

public void ejbCreate();

public void initialize() throws ICSException;

public byte[] loadFileBytes (String your-filename) throws IOException;

public String getURL();

public ICSReply send(ICSClientRequest customer-order) throws ICSException;

public CdkEJB();

public void ejbRemove();

public void ejbActivate();

public void ejbPassivate();

public void setSessionContext (SessionContext sc);

Home Interface

The Home interface declares the create() methods for the CdkEJB class as follows:

CdkRemote create() throws RemoteException, CreateException;

Remote Interface

The Remote interface declares the business logic methods implemented by the bean class. The CdkEJB class implements the following Remote interface methods:

public void initialize() throws ICSException, RemoteException;

public byte[] loadFileBytes(String your-filename) throws IOException, RemoteException;

public String getURL() throws RemoteException;

public ICSReply send(ICSClientRequest customer-order) throws ICSException, RemoteException;

public String getMerchantID() throws RemoteException;

Implementing CDK for Java EJBs

The following steps explain the process for creating, packaging, and deploying CDK for Java EJBs on your EJB-compliant server. Refer to the README_EJB.txt file, included in the distribution file you downloaded, for specific details.

Creating, Packaging, and Deploying CDK for Java EJBs
  1. Edit the default.properties file to assign a time-out value to the transaction.timeout property.
  2. Create the bean with deploytool.
    1. Set the values for the environment variables J2EE_HOME and JAVA_HOME to include the path where you installed the EJB server (J2EE) and Java2 (JDK 1.2).
    2. Select the Stateless session option for the bean.
    3. Set the following environment entries: merchantID, privateKeyFile, myCertFile, serverID, serverCertFile, serverURL, and debug.
    4. Set the option to require container-managed transactions. Be sure to specify an attribute for the send method, setting the Transaction Type to Required.
  3. Deploy the bean.
  4. Include the returned CdkAppClient.jar file in your classpath setting.

When it contacts the EJB server's beans to run a transaction, the EJB client uses the Remote and Home interfaces. See the section CDK for Java EJB Components for a description of the interfaces.

Important  To successfully use the CDK for Java EJBs, your classpath settings must include the paths to the following files: the ICSCdkjava .jar files (ICSCdkjava3500.jar), the JDK files (jdk1.2.2 or jdk1.1.8)(optional), the J2EE file (j2ee.jar), and the deployed bean's .jar file (CdkAppClient.jar).

Testing CDK for Java EJBs

The TestClientEJB.java file, located in the /test/ejb directory, shows how to create an application that uses CyberSource applications. TestClientEJB is a simple application that calls the ICS client libraries and requests an application from the ICS server.

To run TestClientEJB, enter the following command:

java TestClientEJB

The TestFileEJB.java file is included with TestClientEJB. Its standard input is ICS messages that consist of name=value pairs, which TestFileEJB sends to the ICS server. This enables you to quickly test various ICS messages.

The command java TestFileEJB your-infile takes your-infile as input and sends it to the ICS application servers. All of the parameters for TestFileEJB can be set as name=value pairs. TestFileEJB is not required by any applications.

The distribution package provides several additional EJB test suites, located in the /test/ejb directory, that enable you to test the following CyberSource services:

To learn more about the CDK for Java EJB libraries, use the example applications in the test suites. To run the example applications, modify your CLASSPATH setting as explained above in Implementing CDK for Java EJBs.

Syntax for running EJB Test Examples

Use the following syntax to run the EJB test examples (do not include the file extensions .java or .class when you run the test example):

java test-exampleEJB-filename

Refer to the documentation for your EJB server to learn how to compile and run this EJB sample.

Each application offered by CyberSource has its own fields, as well as special rules you must follow when you send ICS requests. See the "Request-Level Field Reference" and "Offer-Level Field Reference" appendices in the ICS2 Developer's Guide, available on the CyberSource Small Business Support Center, for more information about the fields that must be passed for each ICS2 service.

Troubleshooting

This section contains information about common problems you may encounter and provides suggested solutions.

Out of Memory Error Message

If you receive a java.lang.OutOfMemoryError message, you do not have enough RAM allocated for your JVM.

Java Class is Unable to Load the Key or Certificate Files

If your Java class cannot load the required key or certificate files, the suggested resolution depends on which of the ICSClient constructor methods you are using.

Default ICSClient() Constructor

The default constructor for the ICSClient() object takes no parameters. The constructor searches the contents of the ../properties/ICSClient.props file (where ../ is the root directory from which you run the JVM). In order for the ICSClient() constructor to function correctly, your ../properties/ICSClient.props file must contain valid entries for the following properties:

Note  For live transactions, use the URL of the production server (http://ics2.ic3.com:80) as the value for the serverURL property.

ICSClient (String) Constructor

The required entry when using the ICSClient (String) constructor is the path to ICSClient.props file as follows:

ICSClient client = new

ICSClient ("../properties/ICSClient.props");

The filename shown in the example above can be either absolute or relative to the directory from which your JVM is run.

ICSClient(String,String,String,String,String,URL) Constructor

Table 2 shows the required entries when using the ICSClient(String,String,String,String,String,URL) constructor. The filenames in Table 2 can be either absolute or relative to the directory from which your JVM is run.

Table 2 Required ICSClient.props Entries 
ICSClient.props Entry
Explanation
"myPrivateKey",
Your merchant ID.
"../keys/my-assigned-merchant-id.pvt",
The file that contains your private key (the .pvt file generated by ECert).
"../keys/my-assigned-merchant-id.crt",
The file that contains your certificate (the .crt file generated by ECert).
"CyberSource_SJC_US",
A required CyberSource ID, entered exactly as shown.
"../keys/CyberSource_SJC_US.crt",
The CyberSource certificate, entered exactly as shown.
new URL("http://ics2test.ic3.com:80"));
The URL of the CyberSource server. Enter http://ics2test.ic3.com:80 to send test transactions or http://ics2.ic3.com:80 to send live transactions

ICSClient Constructor Causes System Problems

The ICSClient constructors in previous versions of CDK for Java overwrote your System.properties environment. This problem was fixed in version 3.3.0.0 of CDK for Java.

Problems with JSAFE

An ICSClientRequest times out with an error message similar to the following:

-- response --

java.lang.AbstractMethodError: buildObject

at

COM.rsa.jsafe.JSAFE_PrivateKey.getInstance(JSAFE_PrivateKey.java)

at

COM.rsa.jsafe.JSAFE_PrivateKey.getInstance(JSAFE_PrivateKey.java)

at com.xeti.cipher.Crypto.sign(Crypto.java:320)

at com.xeti.pkcs7.SignerInfo.sign(SignerInfo.java:263)

at com.xeti.pkcs7.SignerInfo.(SignerInfo.java:157)

at com.xeti.pkcs7.SignedData.addSigner(SignedData.java:313)

at com.xeti.pkcs7.SignedData.addSigner(SignedData.java:350)

at com.xeti.pkcs7.ContentInfo.sign(ContentInfo.java:663)

at com.xeti.pkcs7.ContentInfo.sign(ContentInfo.java:630)

at com.xeti.pkcs7.P7Composer.sign(P7Composer.java:218)

at com.cybersource.ics.client.message.ICSClient.run

(ICSClient.java)

at java.lang.Thread.run(Thread.java)

ics_rmsg=ICSClientRequest timed out

ics_rcode=1

ics_rflag=ETIMEOUT

request_id=9514307007732183345313

-- end --

This message indicates a classpath problem. Some application servers could have their own version of JSAFE which causes a conflict between libraries.

To resolve the problem, move the entry for the CDK for Java .jar file to the beginning of the classpath environment list.

Using ICSClient with Multiple Threads

CDK for Java supports many threads. It was tested extensively with more than ten threads on Solaris with JDK 1.2.

To ensure that CDK for Java runs well under thread methods, do not instantiate multiple instances of the ICSClient object. The ICSClient object loads the key and certificate files each time it is instantiated.

Once you create an ICSClient object, you can reuse the object as long as the values for merchantID and server are the same. To reuse the ICSClient object, send a new ICSClientRequest object to the ics_send(ICSClientRequest request) function.

If you need your server to support multiple values for merchantID, you must instantiate a new instance of ICSClient for each unique merchantID. You can reuse each unique instance of ICSClient for subsequent threads that involve the same merchantID value.

Missing Resource Exception Error Message

When processing a heavy load — processing many threads — you may receive an exception message similar to the following:

java.util.MissingResourceException: Can't find resource for bundle

java.text.resources.LocaleElements_en_US, key Eras

at java.util.ResourceBundle.getObject(ResourceBundle.java:322)

at java.text.DateFormatSymbols.initializeData(DateFormatSymbols.java:458)

at java.text.DateFormatSymbols.(DateFormatSymbols.java:109)

at java.text.SimpleDateFormat.(SimpleDateFormat.java:286)

at java.util.Date.toString(Date.java:969)

at Worker.run(Worker.java:22)

This is a known JVM bug (#4261469: Race condition in ResourceBundle getBundle/findBundle) that is fixed in JVM versions later than 1.2.2. If you have an account at the Java Developer Connection site (available free of charge), a complete description of the problem associated with these messages is available at the following URL:

http://developer.java.sun.com/developer/bugParade/bugs/4261469.html

Retry Request

Retry Request provides a way for you to get information about a request that has timed out. For more information, see the section "Retry Request" in the ICS2 Developer's Guide, available on the CyberSource Small Business Support Center.

Three parameters allow the user to control how retry requests work.

Important  Retry will not be attempted if the difference between the timeout and retry_start values is less than three seconds.

Retry Request Convenience Methods

To support Retry Request applications, use the following convenience methods:

How Retry Request Works

When retry is enabled, the CDK for Java will:

  1. Encrypt and send the initial request.
  2. Wait until retry_start has expired or return the response if one was received.
  3. If retry_start has expired, the client will encrypt and send the request again.
  4. The client will wait for a response until the full timeout has expired, counting from the time that the initial request was sent.
  5. The client will then return the response, if one was received, or it will return a timeout error.

Enabling Retry

Retry will be disabled by default. To enable retry, set retry_enabled to "yes" in the request message. The value "yes" is case-insensitive.

To enable retry_enabled include the following code:

public void ICSRequest.setRetryEnabled("yes");

Controlling Timeout

Two fields control when retry request occurs and how long the entire ICSClient.send() method will block.

Setting the Timeout Value

The timeout value controls the time allowed for the entire ICS request. This time begins when the initial request is sent. The default for a timeout value is 110 seconds and must not be less than six seconds when retry is enabled. If retry request is disabled, then the timeout value can be less than six seconds (though it is not recommended to set it that low).

You can set the timeout value as follows:

public void ICSRequest.setTimeout(String s);

where s is an integer timeout value, in seconds,

or set the value in the ICSClient.props properties file:

timeout=[integer]

Important  The timeout value must not be set at less than six seconds when retry is enabled. The timeout value must also be greater than the retry_start value by a three second differential. Setting the timeout value is critical because a retry request will not occur if it is set too low.

Testing Retry Request

For information on testing a retry request, see the Chapter "Testing Your System" in the ICS2 Developer's Guide, available on the CyberSource Small Business Support Center.


Copyright © 2002 CyberSource Corporation.
TOC PREV NEXT INDEX