com.boomi.connector.ws

Class WSConnection<C extends BrowseContext>

java.lang.Object

com.boomi.connector.util.BaseConnection<C>

com.boomi.connector.ws.WSConnection<C>

Direct Known Subclasses:

WSOperationConnection

public class WSConnection<C extends BrowseContext>
extends BaseConnection<C>

The WSConnection class is used to implement behavior which is common across all types of interactions with the target web service. This class has a handle to the current Browse/OperationContext and can therefore maintain data which is account specific. This class does not need to be thread-safe as it is only used for a single browse/operation.

The most common customization of this class will be changing how the WebServiceExecutor is configured before execution. The main entry point for this customization is the #configureExecutor method. One common customization is choosing one of the predefined security types, which can be configured by adding a call to configureBasicAuthSecurity(com.boomi.webservices.WebServiceExecutor) or configureUsernameWSSecurity(com.boomi.model.connector.common.webservices.UserTokenPasswordType, com.boomi.webservices.WebServiceExecutor).

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTH_TYPE_PROPERTY connection property which users can use to set the authentication type
static String	DEFAULT_SUCCESS_CODE default status code used for successful response documents
static String	PASSWORD_PROPERTY connection property which users can use to set the password
static String	URL_PROPERTY connection property which users can use to change/specify the base url
static String	USERNAME_PROPERTY connection property which users can use to set the username
static String	WS_SECURITY_PROPERTY connection property which users can use to set the WS-Security options

Constructor Summary

Constructors

Constructor and Description
WSConnection(C context)

Method Summary

Modifier and Type	Method and Description
protected static void	appendErrorDetail(Element detail, StringBuilder sb, List<String> path) Appends any non-empty details to the given StringBuilder.
protected void	configureBasicAuthNonPreemptiveSecurity(com.boomi.webservices.WebServiceExecutor executor) Configures the given WebServiceExecutor for "http basic auth" security support using the username and password retrieved from calls to getUsername() and getPassword().
protected void	configureBasicAuthSecurity(com.boomi.webservices.WebServiceExecutor executor) Configures the given WebServiceExecutor for "http basic auth" security support using the username and password retrieved from calls to getUsername() and getPassword().
protected void	configureCustomWSSecurity(com.boomi.webservices.WebServiceExecutor executor)
protected void	configureSecurity(com.boomi.webservices.WebServiceExecutor executor) Configures the given WebServiceExecutor for security support based on the auth type retrieved from getAuthType(), delegating to configureBasicAuthSecurity(com.boomi.webservices.WebServiceExecutor) or configureUsernameWSSecurity(com.boomi.model.connector.common.webservices.UserTokenPasswordType, com.boomi.webservices.WebServiceExecutor) as appropriate.
protected void	configureUsernameWSSecurity(UserTokenPasswordType pwdType, com.boomi.webservices.WebServiceExecutor executor) Configures the given WebServiceExecutor for "WSSecurity username" security support (for the given password type) using the username and password retrieved from calls to getUsername() and getPassword().
NetworkAuthenticator	createAuthenticator() This method creates a SimpleNetworkAuthenticator for WebServiceAuthenticationType.NETWORK_AUTHENTICATION type connections.
WebServiceAuthenticationType	getAuthType() Returns the authentication configured for this connection.
WSCache	getCache() Returns the connector cache for use for this connection, creating it if necessary.
WSConnector	getConnector() Returns a handle to the connector with which this connection is associated.
String	getDefaultUrl() Returns the "default" url for this web service to be used if none has been configured.
String	getErrorCode(com.boomi.webservices.WebServiceResponse wsResponse) Returns the error status code for the given fault response.
String	getErrorMessage(com.boomi.webservices.WebServiceResponse wsResponse) Returns the error status message for the given fault response.
String	getPassword() Returns the password configured for this connection.
protected SSLContext	getSSLContext() Gets the SSL Context to set on the WebServiceExecutor during call to #configureExecutor.
String	getSuccessCode() Returns the status code to use for successful responses.
String	getSuccessMessage() Returns the status message to use for successful responses.
String	getUrl() Returns the currently configured url for the web service.
protected String	getUrlFromContext() Returns the url configured for this connection.
String	getUsername() Returns the username configured for this connection.
com.boomi.webservices.WSSecurityInfo	getWSSecurityInfo()
boolean	isApplicationFault(com.boomi.webservices.WebServiceResponse wsResponse) Called by operation implementations to determine if the given WebServiceResponse (which is a "fault" response) is an OperationStatus.APPLICATION_ERROR or an OperationStatus.FAILURE.
boolean	isFatalException(Throwable t) Called by operation implementations to determine if the given Throwable is "fatal".
Payload	toPayload(com.boomi.webservices.WebServiceResponse wsResponse) Returns a Payload appropriate for the given WebServiceResponse.

Methods inherited from class com.boomi.connector.util.BaseConnection

generateConnectionInfo, generateConnectionInfo, getContext, getOperationContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

URL_PROPERTY

public static final String URL_PROPERTY

connection property which users can use to change/specify the base url

See Also:

Constant Field Values

USERNAME_PROPERTY

public static final String USERNAME_PROPERTY

connection property which users can use to set the username

See Also:

Constant Field Values

PASSWORD_PROPERTY

public static final String PASSWORD_PROPERTY

connection property which users can use to set the password

See Also:

Constant Field Values

AUTH_TYPE_PROPERTY

public static final String AUTH_TYPE_PROPERTY

connection property which users can use to set the authentication type

See Also:

Constant Field Values

WS_SECURITY_PROPERTY

public static final String WS_SECURITY_PROPERTY

connection property which users can use to set the WS-Security options

See Also:

Constant Field Values

DEFAULT_SUCCESS_CODE

public static final String DEFAULT_SUCCESS_CODE

default status code used for successful response documents

See Also:

Constant Field Values

Constructor Detail

WSConnection

public WSConnection(C context)

Method Detail

getConnector

public WSConnector getConnector()

Returns a handle to the connector with which this connection is associated.

Overrides:

getConnector in class BaseConnection<C extends BrowseContext>

Returns:

the connector

getUrl

public String getUrl()

Returns the currently configured url for the web service.

The default implementation generates the value with a call to getUrlFromContext and caches this value for re-use on subsequent calls.

getUsername

public String getUsername()

Returns the username configured for this connection.

The default implementation returns the connector property with the key USERNAME_PROPERTY.

getPassword

public String getPassword()

Returns the password configured for this connection.

The default implementation returns the connector property with the key PASSWORD_PROPERTY.

getWSSecurityInfo

public com.boomi.webservices.WSSecurityInfo getWSSecurityInfo()

getAuthType

public WebServiceAuthenticationType getAuthType()

Returns the authentication configured for this connection.

The default implementation returns the connector property with the key AUTH_TYPE_PROPERTY, defaulting to WebServiceAuthenticationType.NONE if the property does not exist.

createAuthenticator

public NetworkAuthenticator createAuthenticator()

This method creates a SimpleNetworkAuthenticator for WebServiceAuthenticationType.NETWORK_AUTHENTICATION type connections. This method uses the overridable getAuthType(), getUsername(), and getPassword() to determine the authentication type and create the authenticator. Implementing classes can override these methods to modify those values but still create a simple authenticator. This method can be overridden if a different implementation is required.

Returns:

the network authenticator if created, null otherwise

getDefaultUrl

public String getDefaultUrl()

Returns the "default" url for this web service to be used if none has been configured.

Default implementation returns null.

getUrlFromContext

protected String getUrlFromContext()

Returns the url configured for this connection.

Default implementation returns the connection property with the key URL_PROPERTY if non-blank, otherwise returns the value given by getDefaultUrl().

Throws:

ConnectorException - if a valid url can not be found for the web service

getCache

public WSCache getCache()

Returns the connector cache for use for this connection, creating it if necessary. The cache key will be created by a call to WSConnector.createCacheKey(com.boomi.connector.ws.WSConnection<? extends com.boomi.connector.api.BrowseContext>). If the cache needs to be created, this will be done by a call to WSConnector.createCache(com.boomi.connector.ws.WSCache.Key, com.boomi.connector.api.BrowseContext).

getSSLContext

protected SSLContext getSSLContext()

Gets the SSL Context to set on the WebServiceExecutor during call to #configureExecutor. Default implementation sets the SSL Context to use trusted JVM and deployed atom certificates.

Returns:

SSLContext to set on WebServiceExecutor.

configureSecurity

protected void configureSecurity(com.boomi.webservices.WebServiceExecutor executor)

Configures the given WebServiceExecutor for security support based on the auth type retrieved from getAuthType(), delegating to configureBasicAuthSecurity(com.boomi.webservices.WebServiceExecutor) or configureUsernameWSSecurity(com.boomi.model.connector.common.webservices.UserTokenPasswordType, com.boomi.webservices.WebServiceExecutor) as appropriate. Security for WebServiceAuthenticationType.NETWORK_AUTHENTICATION is handled by WSConnector.createAuthenticator(BrowseContext) so nothing is done to "configure" it here.

configureCustomWSSecurity

protected void configureCustomWSSecurity(com.boomi.webservices.WebServiceExecutor executor)

configureBasicAuthSecurity

protected void configureBasicAuthSecurity(com.boomi.webservices.WebServiceExecutor executor)

Configures the given WebServiceExecutor for "http basic auth" security support using the username and password retrieved from calls to getUsername() and getPassword().

configureBasicAuthNonPreemptiveSecurity

protected void configureBasicAuthNonPreemptiveSecurity(com.boomi.webservices.WebServiceExecutor executor)

Configures the given WebServiceExecutor for "http basic auth" security support using the username and password retrieved from calls to getUsername() and getPassword().

configureUsernameWSSecurity

protected void configureUsernameWSSecurity(UserTokenPasswordType pwdType,
                                           com.boomi.webservices.WebServiceExecutor executor)

Configures the given WebServiceExecutor for "WSSecurity username" security support (for the given password type) using the username and password retrieved from calls to getUsername() and getPassword().

isFatalException

public boolean isFatalException(Throwable t)

Called by operation implementations to determine if the given Throwable is "fatal". Fatal exceptions will cause the entire operation to be aborted, whereas non-fatal exceptions will only fail the current input data.

Default implementation returns false.

isApplicationFault

public boolean isApplicationFault(com.boomi.webservices.WebServiceResponse wsResponse)

Called by operation implementations to determine if the given WebServiceResponse (which is a "fault" response) is an OperationStatus.APPLICATION_ERROR or an OperationStatus.FAILURE. See the sdk documentation for more details on application errors.

Default implementation returns true.

getSuccessCode

public String getSuccessCode()

Returns the status code to use for successful responses. Called by operation implementations when returning successful results.

Default implementation returns DEFAULT_SUCCESS_CODE.

getSuccessMessage

public String getSuccessMessage()

Returns the status message to use for successful responses. Called by operation implementations when returning successful results.

Default implementation returns null.

getErrorCode

public String getErrorCode(com.boomi.webservices.WebServiceResponse wsResponse)

Returns the error status code for the given fault response. Called by operation implementations when returning error results.

Detail implementation returns WebServiceResponse.getErrorCode().

getErrorMessage

public String getErrorMessage(com.boomi.webservices.WebServiceResponse wsResponse)

Returns the error status message for the given fault response. Called by operation implementations when returning error results.

Detail implementation returns WebServiceResponse.getRawErrorMessage() with any detail strings appended to it.

toPayload

public Payload toPayload(com.boomi.webservices.WebServiceResponse wsResponse)
                  throws com.boomi.webservices.WebServiceException

Returns a Payload appropriate for the given WebServiceResponse. Called by operation implementations to convert a WebServiceResponse into a result document. May return null.

Default implementation returns the response body converted to a Payload (using the most efficient conversion possible) if there is a body, null otherwise.

Throws:

com.boomi.webservices.WebServiceException

appendErrorDetail

protected static void appendErrorDetail(Element detail,
                                        StringBuilder sb,
                                        List<String> path)

Appends any non-empty details to the given StringBuilder. Details will be appended using the format: "; =". Detail names will be generated by joining the element names with a '.' character. For example, the detail element of "<error><code>1234</code></error>" will result in the appended string "; error.code=1234".