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.
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 |
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
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.
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
(C) Copyright IBM Corporation 1996, 2005. All Rights Reserved.