com.ibm.etill.framework.clientapi
Class PaymentServerClient

java.lang.Object
  com.ibm.etill.framework.clientapi.PaymentServerClient
Direct Known Subclasses:
PaymentServerSSLClient, PaymentServerTestClient

public class PaymentServerClient
extends java.lang.Object

A PaymentServerClient represents a connection from the merchant program to Commerce Payments. It is a persistent object, designed to be created at the beginning of a merchant program, used and reused throughout that program and closed when the program terminates. PaymentServerClients can be created in several ways to reflect different communication options.

Other communication options are created with subclasses of PaymentServerClient. A PaymentServerSSLClient communicates with Commerce Payments over an SSL connection.

In addition to the standard and SSL clients, CAL provides a test client. This test client is intended to support merchant programmers who need to develop merchant applications that will use payment types that do not yet exist. It is a subclass of PaymentServerClient and can be used throughout most of the merchant's program as a PaymentServerClient. However, when issueCommand is called against a test client, instead of sending the command to Commerce Payments the test client retrieves an XML document from a standard location and uses that as the response. These XML documents should reflect what would be returned by Commerce Payments if the new payment cassette actually existed.

The PaymentServerClient class exports a close method. merchant programs should call close prior to exiting. This is not particularly important for simple programs using standard TCP or SOCKS communication (the Java Runtime will clean up these resources on exit.). However, it is extremely important for SSL clients. Failure to call close on these clients can result in problems when the merchant's application is restarted. Since merchant programs can be converted to use SSL at any time, it would be good practice to ensure that close is called in all cases.


Field Summary
protected java.lang.String dtdPath
Communication
protected java.lang.String hostName
protected java.util.Hashtable httpHeaderFields
protected java.lang.String lastRequest
protected java.lang.String lastXML
protected java.net.Socket socket
protected java.lang.String socksHostName
protected int socksPort
protected int tcpPort
Constructor Summary
PaymentServerClient()
Default constructor.
PaymentServerClient(java.lang.String dtdPath, java.lang.String hostName, int tcpPort)
This constructor creates a Commerce Payments client.
PaymentServerClient(java.lang.String dtdPath, java.lang.String hostName, int tcpPort, java.util.Hashtable httpHeaderFields)
This constructor creates a Commerce Payments client.
PaymentServerClient(java.lang.String dtdPath, java.lang.String hostName, int tcpPort, java.lang.String socksHostName, int socksPort)
This constructor creates a Commerce Payments client.
PaymentServerClient(java.lang.String dtdPath, java.lang.String hostName, int tcpPort, java.lang.String socksHostName, int socksPort, java.util.Hashtable httpHeaderFields)
This constructor creates a Commerce Payments client.
Method Summary
static void addLocaleToHttpHeader(java.util.Hashtable httpHeaderPairs, java.util.Locale locale)
Convert the locale to the form supported by the http protocol and add the accept language tage to the httpHeaderPairs.
void close()
Close (and finalize): Clean up the socket connection when this object goes out of scope using the finalize() method.
protected java.net.Socket connect()
Connect
protected void finalize()
java.lang.String getHostname()
Return the hostname of the Commerce Payments for which this instance was initialized.
java.util.Hashtable getHTTPHeaderFields()
Return the Hashtable of HTTP header fields with which this instance was initialized.
java.lang.String getLastRequest()
Return the last request.
java.lang.String getLastXML()
Return the last XML document.
int getPort()
Return the port number of the Commerce Payments for which this instance was initialized.
java.lang.String getSocksHostname()
Return the hostname of the socks server for which this instance was initialized.
int getSocksPort()
Return the port number of the socks server for which this instance was initialized.
void init(java.lang.String dtdPath, java.lang.String hostName, int tcpPort)
This method initializes the PaymentServerClient object.
void init(java.lang.String dtdPath, java.lang.String hostName, int tcpPort, java.util.Hashtable httpHeaderFields)
This method initializes the PaymentServerClient object.
void init(java.lang.String dtdPath, java.lang.String hostName, int tcpPort, java.lang.String socksHostName, int socksPort)
This method initializes the PaymentServerClient object.
void init(java.lang.String dtdPath, java.lang.String hostName, int tcpPort, java.lang.String socksHostName, int socksPort, java.util.Hashtable httpHeaderFields)
This method initializes the PaymentServerClient object.
PaymentServerResponse issueCommand(java.lang.String command, java.util.Hashtable keywordValuePairs, byte[] pmAuthObject)
Send commands to Commerce Payments.
PaymentServerResponse issueCommand(java.lang.String command, java.util.Hashtable keywordValuePairs, java.util.Hashtable httpHeaderPairs, byte[] pmAuthObject)
Send commands to Commerce Payments.
PaymentServerResponse issueCommand(java.lang.String command, java.util.Hashtable keywordValuePairs, java.util.Hashtable httpHeaderPairs, java.lang.String basicAuthUserid, java.lang.String basicAuthPassword)
Send commands to Commerce Payments.
PaymentServerResponse issueCommand(java.lang.String command, java.util.Hashtable keywordValuePairs, java.lang.String basicAuthUserid, java.lang.String basicAuthPassword)
Send commands to Commerce Payments.
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Field Detail

dtdPath

protected java.lang.String dtdPath
Communication

hostName

protected java.lang.String hostName

tcpPort

protected int tcpPort

socksHostName

protected java.lang.String socksHostName

socksPort

protected int socksPort

httpHeaderFields

protected java.util.Hashtable httpHeaderFields

socket

protected java.net.Socket socket

lastRequest

protected java.lang.String lastRequest

lastXML

protected java.lang.String lastXML
Constructor Detail

PaymentServerClient

public PaymentServerClient()
Default constructor.

PaymentServerClient

public PaymentServerClient(java.lang.String dtdPath,
                           java.lang.String hostName,
                           int tcpPort,
                           java.lang.String socksHostName,
                           int socksPort,
                           java.util.Hashtable httpHeaderFields)
This constructor creates a Commerce Payments client.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
socksHostName - -- socks server's host name.
socksPort - -- socks server's port number.
httpHeaderFields - -- the HTTP header fields hashtable

PaymentServerClient

public PaymentServerClient(java.lang.String dtdPath,
                           java.lang.String hostName,
                           int tcpPort,
                           java.lang.String socksHostName,
                           int socksPort)
This constructor creates a Commerce Payments client.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
socksHostName - -- socks server's host name.
socksPort - -- socks server's port number.

PaymentServerClient

public PaymentServerClient(java.lang.String dtdPath,
                           java.lang.String hostName,
                           int tcpPort,
                           java.util.Hashtable httpHeaderFields)
This constructor creates a Commerce Payments client.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
httpHeaderFields - -- the HTTP header fields hashtable

PaymentServerClient

public PaymentServerClient(java.lang.String dtdPath,
                           java.lang.String hostName,
                           int tcpPort)
This constructor creates a Commerce Payments client.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
Method Detail

getHostname

public java.lang.String getHostname()
Return the hostname of the Commerce Payments for which this instance was initialized.

getPort

public int getPort()
Return the port number of the Commerce Payments for which this instance was initialized.

getSocksHostname

public java.lang.String getSocksHostname()
Return the hostname of the socks server for which this instance was initialized.

getSocksPort

public int getSocksPort()
Return the port number of the socks server for which this instance was initialized.

getHTTPHeaderFields

public java.util.Hashtable getHTTPHeaderFields()
Return the Hashtable of HTTP header fields with which this instance was initialized.

getLastRequest

public java.lang.String getLastRequest()
Return the last request.

getLastXML

public java.lang.String getLastXML()
Return the last XML document.

init

public void init(java.lang.String dtdPath,
                 java.lang.String hostName,
                 int tcpPort,
                 java.lang.String socksHostName,
                 int socksPort,
                 java.util.Hashtable httpHeaderFields)
This method initializes the PaymentServerClient object.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
socksHostName - -- socks server's host name.
socksPort - -- socks server's port number.
httpHeaderFields - -- the HTTP header fields hashtable

init

public void init(java.lang.String dtdPath,
                 java.lang.String hostName,
                 int tcpPort,
                 java.lang.String socksHostName,
                 int socksPort)
This method initializes the PaymentServerClient object.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
socksHostName - -- socks server's host name.
socksPort - -- socks server's port number.

init

public void init(java.lang.String dtdPath,
                 java.lang.String hostName,
                 int tcpPort,
                 java.util.Hashtable httpHeaderFields)
This method initializes the PaymentServerClient object.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.
httpHeaderFields - -- the HTTP header fields hashtable

init

public void init(java.lang.String dtdPath,
                 java.lang.String hostName,
                 int tcpPort)
This method initializes the PaymentServerClient object.
Parameters:
hostName - -- host name of Commerce Payments.
tcpPort - -- port number of the HTTP server used by Commerce Payments. Default is 80.

connect

protected java.net.Socket connect()
                           throws java.io.IOException
Connect

- create and connect a socket

- will be overridden by SSL client (and other subclasses)

Throws:
java.io.IOException

close

public void close()
           throws java.io.IOException
Close (and finalize): Clean up the socket connection when this object goes out of scope using the finalize() method. This is especially important when using SSLSocket objects because those don't get closed like Java does for you for regular sockets.
Throws:
java.io.IOException

finalize

protected void finalize()
                 throws java.lang.Throwable
Throws:
java.lang.Throwable

issueCommand

public PaymentServerResponse issueCommand(java.lang.String command,
                                          java.util.Hashtable keywordValuePairs,
                                          java.lang.String basicAuthUserid,
                                          java.lang.String basicAuthPassword)
                                   throws PaymentServerClientException,
                                          PaymentServerAuthorizationException,
                                          PaymentServerCommunicationException
Send commands to Commerce Payments. IssueCommand throws exceptions in the event of errors or other processing problems.
Parameters:
command - -- the Commerce Payments API command name.
keywordValuePairs - -- the keyword-value pairs to be sent with the Commerce Payments API command.
basicAuthUserid - -- user name used for the basic authentication.
basicAuthPassword - -- password used for the basic authentication.
Returns:
a PaymentServerResponse object.
Throws:
PaymentServerAuthorizationException - This exception is thrown when the command to Commerce Payments is rejected with HTTP 401, Not authorized. It generally indicates either:
  • The merchant programmer provided an incorrect user/password
  • The user has not been properly configured within WebSphere
    PaymentServerCommunicationException - This exception is thrown when CAL is having trouble communicating with Commerce Payments. This exception can mean:
    • CAL received a bad HTTP response; this generally means that something is wrong with the Payment Servlet and or the WebServer/WebSphere configuration.
    • CAL took an IOException, which means that the TCP and or SSL layers threw an IOException (could not connect to Commerce Payments or the connection went down prematurely) If this exception does result from an IOException, the IOException is stored within the communication exception (and can be accessed by the merchant programmer).
      PaymentServerClientException - This is the internal exception thrown by CAL. Also thrown if command is null.

issueCommand

public PaymentServerResponse issueCommand(java.lang.String command,
                                          java.util.Hashtable keywordValuePairs,
                                          byte[] pmAuthObject)
                                   throws PaymentServerClientException,
                                          PaymentServerAuthorizationException,
                                          PaymentServerCommunicationException
Send commands to Commerce Payments. IssueCommand throws exceptions in the event of errors or other processing problems.
Parameters:
command - -- the Commerce Payments API command name.
keywordValuePairs - -- the keyword-value pairs to be sent with the Commerce Payments API command.
pmAuthObject - -- object to be used for authentication
Returns:
a PaymentServerResponse object.
Throws:
PaymentServerAuthorizationException - This exception is thrown when the command to Commerce Payments is rejected with HTTP 401, Not authorized. It generally indicates either:
  • The merchant programmer provided an incorrect user/password
  • The user has not been properly configured within WebSphere
    PaymentServerCommunicationException - This exception is thrown when CAL is having trouble communicating with Commerce Payments. This exception can mean:
    • CAL received a bad HTTP response; this generally means that something is wrong with the Payment Servlet and or the WebServer/WebSphere configuration.
    • CAL took an IOException, which means that the TCP and or SSL layers threw an IOException (could not connect to Commerce Payments or the connection went down prematurely) If this exception does result from an IOException, the IOException is stored within the communication exception (and can be accessed by the merchant programmer).
      PaymentServerClientException - This is the internal exception thrown by CAL. Also thrown if command or pmAuthObject is null.

issueCommand

public PaymentServerResponse issueCommand(java.lang.String command,
                                          java.util.Hashtable keywordValuePairs,
                                          java.util.Hashtable httpHeaderPairs,
                                          java.lang.String basicAuthUserid,
                                          java.lang.String basicAuthPassword)
                                   throws PaymentServerClientException,
                                          PaymentServerAuthorizationException,
                                          PaymentServerCommunicationException
Send commands to Commerce Payments. IssueCommand throws exceptions in the event of errors or other processing problems.
Parameters:
command - -- the Commerce Payments API command name.
keywordValuePairs - -- the keyword-value pairs to be sent with the Commerce Payments API command.
httpHeaderPairs - -- the http header keyword-value pairs to be merged with those used in the constructor values before being sent with the Commerce Payments API command.
basicAuthUserid - -- user name used for the basic authentication.
basicAuthPassword - -- password used for the basic authentication.
Returns:
a PaymentServerResponse object.
Throws:
PaymentServerAuthorizationException - This exception is thrown when the command to Commerce Payments is rejected with HTTP 401, Not authorized. It generally indicates either:
  • The merchant programmer provided an incorrect user/password
  • The user has not been properly configured within WebSphere
    PaymentServerCommunicationException - This exception is thrown when CAL is having trouble communicating with Commerce Payments. This exception can mean:
    • CAL received a bad HTTP response; this generally means that something is wrong with the Payment Servlet and or the WebServer/WebSphere configuration.
    • CAL took an IOException, which means that the TCP and or SSL layers threw an IOException (could not connect to Commerce Payments or the connection went down prematurely) If this exception does result from an IOException, the IOException is stored within the communication exception (and can be accessed by the merchant programmer).
      PaymentServerClientException - This is the internal exception thrown by CAL. Also thrown if command is null.

issueCommand

public PaymentServerResponse issueCommand(java.lang.String command,
                                          java.util.Hashtable keywordValuePairs,
                                          java.util.Hashtable httpHeaderPairs,
                                          byte[] pmAuthObject)
                                   throws PaymentServerClientException,
                                          PaymentServerAuthorizationException,
                                          PaymentServerCommunicationException
Send commands to Commerce Payments. IssueCommand throws exceptions in the event of errors or other processing problems.
Parameters:
command - -- the Commerce Payments API command name.
keywordValuePairs - -- the keyword-value pairs to be sent with the Commerce Payments API command.
httpHeaderPairs - -- the http header keyword-value pairs to be merged with those used in the constructor values before being sent with the Commerce Payments API command.
pmAuthObject - -- object to be used for authentication
Returns:
a PaymentServerResponse object.
Throws:
PaymentServerAuthorizationException - This exception is thrown when the command to Commerce Payments is rejected with HTTP 401, Not authorized. It generally indicates either:
  • The merchant programmer provided an incorrect user/password
  • The user has not been properly configured within WebSphere
    PaymentServerCommunicationException - This exception is thrown when CAL is having trouble communicating with Commerce Payments. This exception can mean:
    • CAL received a bad HTTP response; this generally means that something is wrong with the Payment Servlet and or the WebServer/WebSphere configuration.
    • CAL took an IOException, which means that the TCP and or SSL layers threw an IOException (could not connect to Commerce Payments or the connection went down prematurely) If this exception does result from an IOException, the IOException is stored within the communication exception (and can be accessed by the merchant programmer).
      PaymentServerClientException - This is the internal exception thrown by CAL. Also thrown if command or pmAuthObject is null.

addLocaleToHttpHeader

public static void addLocaleToHttpHeader(java.util.Hashtable httpHeaderPairs,
                                         java.util.Locale locale)
                                  throws PaymentServerClientException
Convert the locale to the form supported by the http protocol and add the accept language tage to the httpHeaderPairs.
Parameters:
httpHeaderPairs - -- the http header keyword-value pairs to be sent with the Commerce Payments API command.
locale - -- the locale to be specified in the PM-Accept-Language tag
Throws:
PaymentServerClientException - This is the internal exception thrown by CAL. Also thrown if command or pmAuthObject is null.

Feedback