com.force.sdk.connector
Class ForceServiceConnector

java.lang.Object
  com.force.sdk.connector.ForceServiceConnector

All Implemented Interfaces:

ForceConnector, com.sforce.ws.SessionRenewer

public class ForceServiceConnector
extends Object
implements ForceConnector, com.sforce.ws.SessionRenewer

A connector to the Force.com service.

This connector will manage and provide connections to the Force.com service. It can provide the following connection types:

• PartnerConnection - Used for SOAP API calls
• MetadataConnection - Used for Force.com's Metadata API
• BulkConnection - Used for Force.com's Bulk API

Connectors require a ForceConnectorConfig to provide connection properties. They can handle ForceConnectorConfigs from the following sources (Note that sources will be checked in this order):

1. An injected ForceConnectorConfig
2. A named source (see ForceConnectorUtils.loadConnectorPropsFromName(String))
3. A ForceConnectorConfig stored in the connector's ThreadLocal cache

Connectors are capable of caching ForceConnectorConfig objects both in a ThreadLocalCache and an in memory cache. The ThreadLocalCache is directly controlled by the caller. The in memory cache is controlled internally by the connector. By default, a connector will cache a ForceConnectorConfig in memory whenever it constructs a connection. However, this can be turned off by the caller.

A ForceServiceConnector provides several additional features beyond the traditional Force.com API Connector. Namely:

• Force.com connection endpoint building with automatic version binding (see ForceConnectorConfig.setAuthEndpoint(String) and ForceConnectorUtils.buildForceApiEndpoint(String))
• Automatic session renewal
• Convenient setting of Force.com connection client identifiers (clientId)

Author:

Tim Kral, Fiaz Hossain

Nested Class Summary

Nested classes/interfaces inherited from interface com.sforce.ws.SessionRenewer

com.sforce.ws.SessionRenewer.SessionRenewalHeader

Field Summary

static QName

SESSION_HEADER_QNAME The qualified name for session SOAP requests.

Fields inherited from interface com.force.sdk.connector.ForceConnector

PROXY_HOST, PROXY_PORT

Constructor Summary

ForceServiceConnector()
Initializes a ForceServiceConnector with no ForceConnectorConfig source.

ForceServiceConnector(ForceConnectorConfig config)
Initializes a ForceServiceConnector which will use the given ForceConnectorConfig to get Force.com connections.

ForceServiceConnector(String connectionName)
Initializes a ForceServiceConnector with a named ForceConnectorConfig source .

Method Summary

void	close() Clears this ForceServiceConnector's local state.
com.sforce.async.BulkConnection	getBulkConnection() Returns a Force.com API BulkConnection.
com.sforce.soap.partner.PartnerConnection	getConnection() Returns a Force.com API PartnerConnection.
String	getConnectionName() Returns the named ForceConnectorConfig source in this ForceServiceConnector.
com.sforce.soap.metadata.MetadataConnection	getMetadataConnection() Returns a Force.com API MetadataConnection.
String	getNamespace() Returns the namespace of the Force.com store to which this ForceServiceConnector is getting a connection.
static ForceConnectorConfig	getThreadLocalConnectorConfig() Retrieves the ForceConnectorConfig found in the ForceServiceConnector ThreadLocal cache.
com.sforce.ws.SessionRenewer.SessionRenewalHeader	renewSession(com.sforce.ws.ConnectorConfig connectorConfig) Automatically renews Force.com timed out sessions.
void	setClientId(String clientId) Sets the Force.com connection client id.
void	setConnectionName(String connectionName) Sets the named ForceConnectorConfig source in this ForceServiceConnector.
void	setConnectorConfig(ForceConnectorConfig connectorConfig) Sets the ForceConnectorConfig state in this ForceServiceConnector.
void	setSkipCache(boolean skipCache) Indicates whether or not this ForceServiceConnector should skip in memory ForceConnectorConfig cache reads and writes.
static void	setThreadLocalConnectorConfig(ForceConnectorConfig config) Sets the ForceConnectorConfig in the ForceServiceConnector ThreadLocal.
void	setTimeout(int timeout) Sets the read timeout for all Force.com connections gotten by this ForceServiceConnector.

Methods inherited from class java.lang.Object

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

Field Detail

SESSION_HEADER_QNAME

public static final QName SESSION_HEADER_QNAME

The qualified name for session SOAP requests.

Constructor Detail

ForceServiceConnector

public ForceServiceConnector()

Initializes a ForceServiceConnector with no ForceConnectorConfig source.

If using this constructor, the caller must provider a ForceConnetorConfig source via setters before getting a Force.com connection.

See Also:

setConnectorConfig(ForceConnectorConfig), setConnectionName(String), setThreadLocalConnectorConfig(ForceConnectorConfig)

ForceServiceConnector

public ForceServiceConnector(String connectionName)

Initializes a ForceServiceConnector with a named ForceConnectorConfig source .

Parameters:

connectionName - the named ForceConnectorConfig source from which a valid ForceConnectorConfig can be constructed and used to get Force.com connections

See Also:

ForceConnectorUtils.loadConnectorPropsFromName(String)

ForceServiceConnector

public ForceServiceConnector(ForceConnectorConfig config)
                      throws com.sforce.ws.ConnectionException

Initializes a ForceServiceConnector which will use the given ForceConnectorConfig to get Force.com connections.

Parameters:

config - the ForceConnectorConfig to be used when getting Force.com connections

Throws:

IllegalArgumentException - if the given ForceConnectorConfig is null

com.sforce.ws.ConnectionException - if the given ForceConnectorConfig is incomplete (i.e. cannot be used to get a Force.com connection)

Method Detail

getThreadLocalConnectorConfig

public static ForceConnectorConfig getThreadLocalConnectorConfig()

Retrieves the ForceConnectorConfig found in the ForceServiceConnector ThreadLocal cache.

Returns:

the ForceConnectorConfig from the ThreadLocal; null if no such ForceConnectorConfig exists

setThreadLocalConnectorConfig

public static void setThreadLocalConnectorConfig(ForceConnectorConfig config)

Sets the ForceConnectorConfig in the ForceServiceConnector ThreadLocal.

Parameters:

config - the ForceConnectorConfig to be set in the ThreadLocal

getConnection

public com.sforce.soap.partner.PartnerConnection getConnection()
                                                        throws com.sforce.ws.ConnectionException

Returns a Force.com API PartnerConnection.

This connection type can be use to make SOAP API calls to the Force.com service. The PartnerConnection will be lazily constructed and stored in this ForceServiceConnector's state. This state can be cleared with a call to close

Returns:

a Force.com API PartnerConnection from the ForceConnectorConfig state found in this ForceServiceConnector

Throws:

com.sforce.ws.ConnectionException - if the ForceConnectorConfig state cannot be found or otherwise constructed

com.sforce.ws.ConnectionException - if this ForceServiceConnector cannot get a connection to the Force.com service with its ForceConnectorConfig state

See Also:

renewSession(ConnectorConfig), close()

getMetadataConnection

public com.sforce.soap.metadata.MetadataConnection getMetadataConnection()
                                                                  throws com.sforce.ws.ConnectionException

Returns a Force.com API MetadataConnection.

This connection type can be use to make Force.com Metadata API calls to the Force.com service. The MetadataConnection will be lazily constructed and stored in this ForceServiceConnector's state. This state can be cleared with a call to close

Returns:

a Force.com API MetadataConnection from the ForceConnectorConfig state found in this ForceServiceConnector

Throws:

com.sforce.ws.ConnectionException - if the ForceConnectorConfig state cannot be found or otherwise constructed

com.sforce.ws.ConnectionException - if this ForceServiceConnector cannot get a connection to the Force.com service with its ForceConnectorConfig state

See Also:

renewSession(ConnectorConfig), close()

getBulkConnection

public com.sforce.async.BulkConnection getBulkConnection()
                                                  throws com.sforce.ws.ConnectionException,
                                                         com.sforce.async.AsyncApiException

Returns a Force.com API BulkConnection.

This connection type can be use to make Force.com Bulk API calls to the Force.com service. The BulkConnection will be lazily constructed and stored in this ForceServiceConnector's state. This state can be cleared with a call to close

Returns:

a Force.com API BulkConnection from the ForceConnectorConfig state found in this ForceServiceConnector

Throws:

com.sforce.ws.ConnectionException - if the ForceConnectorConfig state cannot be found or otherwise constructed

com.sforce.ws.ConnectionException - if this ForceServiceConnector cannot get a connection to the Force.com service with its ForceConnectorConfig state

com.sforce.async.AsyncApiException - if this ForceServiceConnector cannot load a BulkConnection to the Force.com service with its ForceConnectorConfig state

See Also:

renewSession(ConnectorConfig), close()

getNamespace

public String getNamespace()
                    throws com.sforce.ws.ConnectionException

Returns the namespace of the Force.com store to which this ForceServiceConnector is getting a connection.

A namespace uniquely identifies a Force.com store on the Force.com service. This ForceServiceConnector will retrieve the namespace by getting a Force.com connection with its ForceConnectorConfig state.

Returns:

the unique Force.com store namespace; null is no such namespace exists

Throws:

com.sforce.ws.ConnectionException - if the ForceConnectorConfig state cannot be found or otherwise constructed

com.sforce.ws.ConnectionException - if this ForceServiceConnector cannot get a connection to the Force.com service with its ForceConnectorConfig state

com.sforce.ws.ConnectionException - if the namespace cannot be retrieved over the Force.com connection

close

public void close()

Clears this ForceServiceConnector's local state.

The connections gotten by a ForceServiceConnector are lazily constructed and stored in the ForceServiceConnector's local state. Thus multiple calls to get a connection will return the same connection object without re-establishing a connection to the Force.com service. The close method forces this ForceServiceConnector to re-establish a connection with the Force.com service by clearing its local state.

See Also:

getConnection(), getMetadataConnection(), getBulkConnection(), renewSession(ConnectorConfig)

renewSession

public com.sforce.ws.SessionRenewer.SessionRenewalHeader renewSession(com.sforce.ws.ConnectorConfig connectorConfig)
                                                               throws com.sforce.ws.ConnectionException

Automatically renews Force.com timed out sessions.

The connections gotten by a ForceServiceConnector are lazily constructed and stored in the ForceServiceConnector's local state. Thus multiple calls to get a connection will return the same connection object without re-establishing a connection to the Force.com service. However, this presents a problem should the Force.com session expire. In that case, stored connections will have their session automatically renewed by the renewSession.

Specified by:

renewSession in interface com.sforce.ws.SessionRenewer

Parameters:

connectorConfig - the ForceConnectorConfig to be used to re-establish a Force.com connection

Returns:

a session renewal SOAP header

Throws:

com.sforce.ws.ConnectionException - if the Force.com connection cannot be re-established

See Also:

getConnection(), getMetadataConnection(), getBulkConnection(), close()

setClientId

public void setClientId(String clientId)

Sets the Force.com connection client id.

The client id is a String identifier which will be set on the Force.com connection gotten by this ForceServiceConnector. Note that the client id set here will override the client id in this ForceServiceConnector's ForceConnectorConfig state.

Parameters:

clientId - any non null, non empty String that is to be used as a Force.com connection identifier

getConnectionName

public String getConnectionName()

Returns the named ForceConnectorConfig source in this ForceServiceConnector.

A named ForceConnectorConfig source specifies connection properties in a named location. These properties can be used to construct a ForceConnectorConfig.

Returns:

a named ForceConnectorConfig source

See Also:

ForceConnectorUtils.loadConnectorPropsFromName(String)

setConnectionName

public void setConnectionName(String connectionName)

Sets the named ForceConnectorConfig source in this ForceServiceConnector.

A named ForceConnectorConfig source specifies connection properties in a named location. These properties can be used to construct a ForceConnectorConfig. Note that a named connection ForceConnectorConfig source can be overridden by directly injecting ForceConnectorConfig state.

Parameters:

connectionName - the name of a ForceConnectorConfig source

See Also:

ForceConnectorUtils.loadConnectorPropsFromName(String), setConnectorConfig(ForceConnectorConfig)

setConnectorConfig

public void setConnectorConfig(ForceConnectorConfig connectorConfig)

Sets the ForceConnectorConfig state in this ForceServiceConnector.

The ForceConnectorConfig state is used by a ForceServiceConnector to get connections to the Force.com service. Note that setting this state will override any named ForceConnectorConfig source set in this ForceServiceConnector.

Parameters:

connectorConfig - the ForceConnectorConfig be to used to get Force.com connection within this ForceServiceConnector

See Also:

ForceConnectorUtils.loadConnectorPropsFromName(String), setConnectionName(String)

setSkipCache

public void setSkipCache(boolean skipCache)

Indicates whether or not this ForceServiceConnector should skip in memory ForceConnectorConfig cache reads and writes.

By default, a ForceServiceConnector will cache ForceConnectorConfig objects when getting a connection to the Force.com service. This state allows the caller to control whether that cache is used or not.

Parameters:

skipCache - boolean to indicate whether this ForceServiceConnector should ignore the ForceConnectorConfig in memory cache

setTimeout

public void setTimeout(int timeout)

Sets the read timeout for all Force.com connections gotten by this ForceServiceConnector.

Note that this timeout value will override any read timeout value set in a ForceConnectorConfig.

Parameters:

timeout - the Force.com connection read timeout in milliseconds