com.sap.portal.connectivity.destinations

Interface IDestinationsService

All Known Implementing Classes:

DestinationServiceImpl

public interface IDestinationsService

This library enables retrival of all back-ends connection definitions which can be consumed via Connector Framework implementing connectors. The definition of how to connect to a back-end can be stored in various repository source like:

• Portal System Landscape
• J2EE Destination Service
• Web Service Logical Destination (a.k.a "Logical Port")
• WebDynPro JCo Destinations

Each one of the above back-end definition source can hold more than one type of back-ends (e.g. the Portal System Landscape can hold connection definition to a SAP system, a RDBMS, a Web Service etc). The library enables the client to get a list of destination names (filtered by their source and type) The library enables the client to get information for a given destination name - its source and type. The library enables the client to get a Connector Framework connection to a given destination name.
The API are exposed as a J2EE library and therefor can be consumed from any J2EE component type.
A portal service for same API is available as well To retrieve the service instance from a portal application, add com.sap.portal.ivs.connectorservice in the portalapp.xml references list and use:

IDestinationsService destinationsService = (IDestinationsService) PortalRuntime.getRuntimeResources().getService(IDestinationsService.KEY);

To retrieve the service from other type of component, add to your component a reference to J2EE library com.sap.portal.services.api and use:

IDestinationsService destinationsService = ServicesFactory.getDestinationService();

Code sample of using this service:

String[] destinationNames;
String destinationName;
IDestinationWrapper destinationWrapper;
IConnection connection = null;
DestinationFilter destinationFilter1 = new DestinationFilter(DestinationFilter.SOURCE_PORTAL_SYSTEM_LANDSCAPE_SERVICE, DestinationFilter.TYPE_ALL);
DestinationFilter destinationFilter2 = new DestinationFilter(DestinationFilter.SOURCE_J2EE_DESTINATION_SERVICE, DestinationFilter.TYPE_SAP);
DestinationFilter[] destinationFilters = new DestinationFilter[] {destinationFilter1, destinationFilter2};
destinationNames = destinationsService.getDestinationNames(myUser, destinationFilters);

boolean hintAreCredentialsSet;
for (int i = 0; i < destinationNames.length; i++) {
        destinationName = destinationNames[i];
        try {
                destinationWrapper = destinationsService.getDestinationWrapper(myUser, destinationName);
                hintAreCredentialsSet = destinationWrapper.hintAreCredentialsSet(myUser);
                if (hintAreCredentialsSet) {
                        connection = destinationsService.getConnection(myUser, destinationName);
                } else {
                        // get credential (e.g. popup a logon window)
                        connection = destinationsService.getConnection(myUser, destinationName, "myUserName", "myPassword");
                }
                // consume the back-end
        } catch (Exception e) {
                // error handling
        } finally {
                if (connection != null) {
                        try {
                                connection.close();
                        } catch (ResourceException e1) {
                                // error handling
                        }
                }
        }
}

When this service needs to lookup for a destination retriever, or, get a connection by a destination name, it searches its registered implementations by the order they were registered.
The API also enables to override connection spec values for a destination. see getConnection(IUser, String, Map)

In cases where back-end require a language to connect with (e.g. SAP systems), the value is taken from IUser.getLocale().getLanguage() (default is "EN"). Client can override language value by using one of the overriding methods detailed below. This is a common case for portal scenarios where locale can be determined in various levels (portal component, portal runtime etc). The following code will set same language as portal locale would:

overridingConnectionSpecProps.put(IConnectionSpecMetaData.CONNECTION_PROPERTY_LANGUAGE, myPortalRequest.getLocale().getLanguage());

Client may create his own destination retriever source by implementing AbstractDestinationsRetrieverSource and registering it with registerDestinationSourceRetriever(AbstractDestinationsRetrieverSource).

Field Summary

static String	KEY Constant for portal service KEY (portal application name + service name in portalapp.xml)
static String	SERVICE_JNDI_NAME JNDI lookup name for this service (if using portal JNDI factory)

Method Summary

IConnection	getConnection(com.sap.security.api.IUser user, String destinationName) Gets a connection to a back-end by its destination name.
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, DestinationFilter destinationFilter) Gets a connection to a back-end by its destination name from matching the filter destination source and type.
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, DestinationFilter destinationFilter, Map<String,Object> overridingConnectionSpecProps) Gets Connector Framework connection to the back-end to a given destination name.
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, DestinationFilter destinationFilter, String forcedUserName, String forcedPassword) Same as getConnection(IUser,String,String,String) with enforced filter
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, int enforceSource) Deprecated. Use getConnection(IUser,String,DestinationFilter)
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, int enforceSource, String forcedUserName, String forcedPassword) Deprecated. Use getConnection(IUser,String,DestinationFilter,String,String)
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, Map<String,Object> overridingConnectionSpecProps) Gets Connector Framework connection to the back-end to a given destination name.
IConnection	getConnection(com.sap.security.api.IUser user, String destinationName, String forcedUserName, String forcedPassword) Gets Connector Framework connection to the back-end to a given destination name.
IConnectionFactory	getConnectionFactory(String jndiName) Gets an instance of IConnectionFactory for a given JNDI name of Connector Framework implementing connector
String[]	getDestinationNames(com.sap.security.api.IUser user) Returens list of destination names of all supported types
String[]	getDestinationNames(com.sap.security.api.IUser user, DestinationFilter[] destinationFilters) Returens list of destination names matching given destination filters filters
IDestinationWrapper	getDestinationWrapper(com.sap.security.api.IUser user, String destinationName) Gets a destination wrapper by the destination name
IDestinationWrapper	getDestinationWrapper(com.sap.security.api.IUser user, String destinationName, DestinationFilter destinationFilter) Gets a destination wrapper by the destination name matching the given filter
AbstractDestinationsRetrieverSource	getRegisteredDestinationSource(String key) Returns a destination retriever source by its key
List	getRegisteredDestinationSourcesKeys() Returns a list of registered destination source keys by the order they were registered
void	registerDestinationSourceRetriever(AbstractDestinationsRetrieverSource retrieverSource) Registers a destination retriever source
void	unregisterDestinationSourceRetriever(String key) Unregisters a destination retriever source

Field Detail

KEY

static final String KEY

Constant for portal service KEY (portal application name + service name in portalapp.xml)

See Also:

Constant Field Values

SERVICE_JNDI_NAME

static final String SERVICE_JNDI_NAME

JNDI lookup name for this service (if using portal JNDI factory)

See Also:

Constant Field Values

Method Detail

getDestinationNames

String[] getDestinationNames(com.sap.security.api.IUser user)

Returens list of destination names of all supported types

Parameters:

user - The user requesting the destinations list (some destinations source types require authentication to be get)

Returns:

returns an array of destination names

getDestinationNames

String[] getDestinationNames(com.sap.security.api.IUser user,
                             DestinationFilter[] destinationFilters)

Returens list of destination names matching given destination filters filters

Parameters:

user - The user requesting the destinations list (some destinations source types require authentication to be get)

destinationFilters - filters array of destination source and type e.g new DestinationFilter(IDestinationWrapper.SOURCE_PORTAL_SYSTEM_LANDSCAPE_SERVICE, IDestinationWrapper.TYPE_SAP)

Returns:

returns an array of destination names

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          int enforceSource)
                          throws PortalDestinationsServiceException

Deprecated. Use getConnection(IUser,String,DestinationFilter)

Gets a connection to a back-end by its destination name and source type.

Parameters:

user - User for retrieving the connection to

destinationName - name of the destination to get connection to

enforceSource - the source of the destination (since same destination name may exists on different sources)

Returns:

a connection to the back-end

Throws:

PortalDestinationsServiceException

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          DestinationFilter destinationFilter)
                          throws PortalDestinationsServiceException

Gets a connection to a back-end by its destination name from matching the filter destination source and type.

Parameters:

user - User for retrieving the connection to

destinationName - name of the destination to get connection to

destinationFilter - Enforce to match destination retriever of specific source and specific back end type

Returns:

a connection to the back-end

Throws:

PortalDestinationsServiceException

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName)
                          throws PortalDestinationsServiceException

Gets a connection to a back-end by its destination name.

Parameters:

user - User for retrieving the connection to

destinationName - name of the destination to get connection to

Returns:

a connection to the back-end

Throws:

PortalDestinationsServiceException

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          int enforceSource,
                          String forcedUserName,
                          String forcedPassword)
                          throws PortalDestinationsServiceException

Deprecated. Use getConnection(IUser,String,DestinationFilter,String,String)

Same as getConnection(IUser,String,String,String) with enforced source

Parameters:

user - logged-on user to connect with

destinationName - the name of the destination to connect to

enforceSource - the source of the destination

forcedUserName - user name to connect with to the back-end

forcedPassword - password to connect with to the back-end

Returns:

IConnection to the back-end

Throws:

PortalDestinationsServiceException - when fail to get a connection (e.g. no such destination name in the source repository, rejection from the back-end etc)

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          DestinationFilter destinationFilter,
                          String forcedUserName,
                          String forcedPassword)
                          throws PortalDestinationsServiceException

Same as getConnection(IUser,String,String,String) with enforced filter

Parameters:

user - logged-on user to connect with

destinationName - the name of the destination to connect to

destinationFilter - filter for the source, type and SAP type

forcedUserName - user name to connect with to the back-end

forcedPassword - password to connect with to the back-end

Returns:

IConnection to the back-end

Throws:

PortalDestinationsServiceException - when fail to get a connection (e.g. no such destination name in the source repository, rejection from the back-end etc)

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          String forcedUserName,
                          String forcedPassword)
                          throws PortalDestinationsServiceException

Gets Connector Framework connection to the back-end to a given destination name. The connection is established overriding the destination definition of credentials. e.g. destination is set to use SSO, or username/password are not defined in the destination, the method will use the given user name and password

Parameters:

user - logged-on user to connect with

destinationName - the name of the destination to connect to

forcedUserName - user name to connect with to the back-end

forcedPassword - password to connect with to the back-end

Returns:

IConnection to the back-end

Throws:

PortalDestinationsServiceException - when fail to get a connection (e.g. no such destination name in the source repository, rejection from the back-end etc)

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          Map<String,Object> overridingConnectionSpecProps)
                          throws PortalDestinationsServiceException

Gets Connector Framework connection to the back-end to a given destination name. The connection is established overriding the destination definition of any connection spec value available in the overridingConnectionSpecProps parameter. Clients of this API should be familiar with the back-end connection spec, or, may discover the connection spec using Connector Framework API via IConnectionSpecMetaData

Parameters:

user - logged-on user to connect with

destinationName - the name of the destination to connect to

overridingConnectionSpecProps - Map of connection spec keys and values to override back-end connection spec as stored in the destination definition

Returns:

IConnection to the back-end

Throws:

PortalDestinationsServiceException

getConnection

IConnection getConnection(com.sap.security.api.IUser user,
                          String destinationName,
                          DestinationFilter destinationFilter,
                          Map<String,Object> overridingConnectionSpecProps)
                          throws PortalDestinationsServiceException

Gets Connector Framework connection to the back-end to a given destination name. The connection is established overriding the destination definition of any connection spec value available in the overridingConnectionSpecProps parameter. Clients of this API should be familiar with the back-end connection spec, or, may discover the connection spec using Connector Framework API via IConnectionSpecMetaData

Parameters:

user - logged-on user to connect with

destinationName - the name of the destination to connect to

destinationFilter - filter for the source, type and SAP type

overridingConnectionSpecProps - Map of connection spec keys and values to override back-end connection spec as stored in the destination definition

Returns:

IConnection to the back-end

Throws:

PortalDestinationsServiceException

getDestinationWrapper

IDestinationWrapper getDestinationWrapper(com.sap.security.api.IUser user,
                                          String destinationName)
                                          throws PortalDestinationsServiceException

Gets a destination wrapper by the destination name

Parameters:

destinationName - name of the destination

Returns:

a wrapper to the destinations, null if no destination is matching the given name

Throws:

PortalDestinationsServiceException

getDestinationWrapper

IDestinationWrapper getDestinationWrapper(com.sap.security.api.IUser user,
                                          String destinationName,
                                          DestinationFilter destinationFilter)
                                          throws PortalDestinationsServiceException

Gets a destination wrapper by the destination name matching the given filter

Parameters:

destinationName - name of the destination

destinationFilter - filter for the source and type

Returns:

a wrapper to the destinations, null if no destination is matching the given name

Throws:

PortalDestinationsServiceException

registerDestinationSourceRetriever

void registerDestinationSourceRetriever(AbstractDestinationsRetrieverSource retrieverSource)

Registers a destination retriever source

Parameters:

retrieverSource - the source to register

unregisterDestinationSourceRetriever

void unregisterDestinationSourceRetriever(String key)

Unregisters a destination retriever source

Parameters:

key - the destination source key

getRegisteredDestinationSourcesKeys

List getRegisteredDestinationSourcesKeys()

Returns a list of registered destination source keys by the order they were registered

Returns:

list of String

getRegisteredDestinationSource

AbstractDestinationsRetrieverSource getRegisteredDestinationSource(String key)

Returns a destination retriever source by its key

Parameters:

key - the destination retriever key

Returns:

the destination retriever

getConnectionFactory

IConnectionFactory getConnectionFactory(String jndiName)

Gets an instance of IConnectionFactory for a given JNDI name of Connector Framework implementing connector

Parameters:

jndiName - JNDI name of the connector as its registered in the WebAS

Returns:

IConnectionFactory instance

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] EP-CONNECTIVITY	[sap.com] tc/pp/smntcs/int/portalservicesapilibdeprecated	api	EP-VC-CON
[sap.com] EP-CONNECTIVITY	[sap.com] tc/ep/connectivity/api	api	EP-VC-CON
[sap.com] EP-CONNECTIVITY	[sap.com] tc/ep/connectivity/lib/api	api	EP-VC-CON