|
Search documentation: |
Help Advanced | |
Published 05/14/2002 |
![]() ![]() ![]() ![]() |
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
- System Requirements
- Installing the ICS Java Client Libraries
- Testing Your Installation
- Constructing and Sending SCMP Messages
- Using Enterprise Java Beans
- Troubleshooting
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:
- Ensure that your environment meets the System Requirements.
- Download the distribution file.
- Install the ICS Java client libraries (as described in Installing the ICS Java Client Libraries).
- Run the ECert application to generate a private key and certificate to enter in the ICSClient.props file (see "Generating Your Certificate and Private Key" in the ICS2 Developer's Guide, available on the CyberSource Small Business Support Center).
- Update your classpath environment variable to point to the directory where the CyberSource Developer Kit (CDK) for Java .jar file was copied (as described in Installing the ICS Java Client Libraries).
- Modify the entries for merchantID, myPrivateKey, and myCert in the ICSClient.props file (located in the properties directory) to match your CyberSource merchant ID and the private key and certificate you generated with the ECert application. By default, the URL assigned to serverURL points to the ICS2 test server (ics2test.ic3.com).
- Test your application against ics2test.ic3.com (as described in Testing Your Installation).
- When you are ready to send live transactions, modify the serverURL entry in the ICSClient.props file to point to the ICS2 production server's URL (ics2.ic3.com).
Important To connect to the CyberSource ICS application servers to either test or go live, you must first update ICSClient.props file with your merchant ID and the private key and certificate information generated by ECert. See "Constructing and Sending SCMP Messages" for instructions.
System Requirements
You must have root or administrator privileges to use the ICS Java client libraries, along with the following minimum requirements:
- Java Development Kit (JDK) version 1.1.8, 1.2.2 or later, installed and running.
- 128 MB RAM allocated to your Java Virtual Machine (JVM).
- Solaris 2.6 operating system on SPARC, or Windows NT Server 4.0 on Intel.
- 10 MB of disk space.
- A utility to uncompress the distribution file.
- If you plan to use Enterprise Java Beans (EJBs), you must have Java2 Platform Enterprise Edition and JDK 1.2.2 installed and running on your server.
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:
- Create a target directory.
- Uncompress the distribution file you downloaded. For the destination, specify the directory you created in Step 1.
- Modify the classpath variable to point to the directory that contains the cdkjava11_3500.jar or cdkjava12_3500.jar file.
- 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:
- Right-click the My Computer icon.
- Select Properties.
- In the Properties dialog box, select the Environment tab.
- 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.- Restart the computer.
- 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
- Ensure that the CDK is properly installed and that the classpath is set (as described in Installing the ICS Java Client Libraries).
- Change to the test subdirectory where you installed CDK for Java.
- At a shell prompt, enter the following command:
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 FilesEach 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();
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:
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:
- Displays an order form to an eCommerce customer's Web browser
- Retrieves the information provided by the customer
- Sends the required offer fields to the CyberSource ICS2 server
- Retrieves the ICS2 server's reply message
- Displays the appropriate response to the customer, based on the ICS2 server's reply message
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:
- EJBs — predefined, object-oriented components that are deployed in EJB containers on the server for the client to access. When an EJB is deployed in a container, an EJB Home interface is automatically generated to represent the bean class, and an EJB Object interface is created for each bean instance.
- EJB clients — request the EJBs that are deployed within containers on an EJB-compliant server. The client uses the Java Naming and Directory Interface (JNDI) to find the container with the requested EJB.
- EJB-compliant server — provide system services to clients and store EJBs in containers for access by clients.
- EJB containers — reside on the server and act as an interface between an EJB and the client. The client itself never directly accesses an EJB.
- There are two types of EJB containers:
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 initialize() throws ICSException;
public byte[] loadFileBytes (String your-filename) throws IOException;
public ICSReply send(ICSClientRequest customer-order) throws ICSException;
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
- Edit the default.properties file to assign a time-out value to the
transaction.timeout
property.- Create the bean with deploytool.
- Set the values for the environment variables
J2EE_HOME
andJAVA_HOME
to include the path where you installed the EJB server (J2EE) and Java2 (JDK 1.2).- Select the Stateless session option for the bean.
- Set the following environment entries:
merchantID
,privateKeyFile
,myCertFile, serverID, serverCertFile, serverURL,
anddebug
.- Set the option to require container-managed transactions. Be sure to specify an attribute for the send method, setting the Transaction Type to
Required
.- Deploy the bean.
- 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:
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):
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:
serverName
= CyberSource_SJC_US
merchantID
= <
your-assigned-merchant-id>
myPrivateKey
= <
keys directory
>/<
your-assigned-merchant-id>.pvt
myCert
=
<keys directory
>/<
your-assigned-merchant-id>.crt
serverURL
= http://ics2test.ic3.com:80
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 ("../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 EntriesICSClient 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:
java.lang.AbstractMethodError: buildObject
COM.rsa.jsafe.JSAFE_PrivateKey.getInstance(JSAFE_PrivateKey.java)
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
at java.lang.Thread.run(Thread.java)
ics_rmsg=ICSClientRequest timed out
request_id=9514307007732183345313
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)
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.
- retry_enabled - indicates whether the user wants the client to attempt a retry request if necessary. Retry request is disabled by default.
- retry_start - controls how long the client waits for the initial response before attempting retry. Minimum value is three seconds. Default value is 30 seconds.
- timeout - controls how long the send function blocks before it returns a timeout error (whether retry was attempted or not). Minimum value is six with retry enabled. Default value is 110 seconds.
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:
void ICSRequest.setTimeout(String s);
- where s is an integer timeout value, in seconds.
String ICSRequest.getTimeout();
void ICSRequest.setRetryEnabled(String s);
- where s is either "yes" or "no"
.
String ICSRequest.getRetryEnabled();
void ICSRequest.setRetryStart(String s);
- where s is an integer value, in seconds
.
String ICSRequest.getRetryStart();
How Retry Request Works
When retry is enabled, the CDK for Java will:
- Encrypt and send the initial request.
- Wait until retry_start has expired or return the response if one was received.
- If retry_start has expired, the client will encrypt and send the request again.
- The client will wait for a response until the full timeout has expired, counting from the time that the initial request was sent.
- 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.
- timeout — controls how long the ICSClient.send() method will block.
- For example, if timeout is set to 60, then ICSClient.send() method will block for a maximum of 60 seconds, regardless of whether retry is enabled or not. If no response has been received within that time, then a timeout error will be returned.
- retry_start — controls how long the client should wait before sending a retry request. The default value is 30 seconds.
- After the initial request times out (elapsed time is greater than the retry_start), the client will send a retry request with a timeout value equal to the timeout minus retry_start.
- You can set the retry_start value as follows:
public void ICSRequest.setRetryStart(String s)
;- where s is an integer value, in seconds
- or set the value in the ICSClient.props properties file:
retryStart=[integer]
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:
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. |
![]() |
![]() |
![]() |
![]() |