com.sap.tc.webdynpro.modelimpl.dynamicrfc
Interface IWDDynamicRFCModel

All Superinterfaces:

com.sap.tc.cmi.model.ICMIModel, IWDModel, IWDModelRegistry

public interface IWDDynamicRFCModel

extends IWDModel, IWDModelRegistry

Provides access to all generic functionality that an Adaptive RFC Model implements.

Beside the functionality defined through the extended interfaces (originating from the Common Model Interface (CMI) and the Web Dynpro Model Interface), this includes mainly connection management.

Application frameworks can cast from generated Adaptive RFC Models to this interface if they need to deal with generated Models in a generic way (e.g. when developing application frameworks).

Connection Management

The connection management works as follows:

• When the execute() method of an executable ModelClass instance is called, a connection (a JCO.Client) is needed. This connection is retrieved from the Model instance to which the ModelClass instance belongs (this is defined as the Model instance with the same scope and instanceId as the ModelClass instance).
• A Model instance is initialized with the default logical system name that has been declared at design time. This name can be used to retrieve a JCO.Client from the WDSystemLandscape service which in turn queries the System Landscape Directory (SLD).
• The JCO.Client to be used by a Model instance can be set at any time using one of the following options (with increasing priority):
  1. Use the Model's default as declared at design time in the IDE using the setting "defaultLogicalSystemName"
  2. Set the JCO.Client implicitly by setting a logical system name using setSystemName(String)
  3. Set the JCO.Client explicitly using setJcoClient(JCO.Client)
  4. Set the JCO.Client implicitly using setConnectionProvider(IWDDynamicRFCModel). This Model will share the connection with the given model, which is the only responsible for that connection. See "Sharing Connections" below for details.
  See method getCurrentlyUsedJcoClient() for details.

When multiple of the methods above are called, the one with the highest priority will determine the active JCO.Client. This means, that setting another Model instance as connection provider will override setting the JCO.Client explicitly, which in turn will override any logicalSystemName, and setting a logicalSystemName will override the defaultLogicalSystemName.

Calling one of the methods above with an argument of null will reset (undo) any previous call of the same method. E.g. setJcoClient(null) will cause the logicalSystemName to be used to attain a JCO.Client (if given, otherwise the default is used). setLogicalSystemName(null) will cause the defaultLogicalSystemName to be used (unless a JCO.Client was set explicitly), setLogicalSystemName(null) and setJcoClient(null) will cause the defaultLogicalSystemName to be used.

Sharing connections between multiple Models

Setting the JCO.Client implicitly by setting a connection provider using setConnectionProvider(IWDDynamicRFCModel) allows sharing a connection between multiple Model instances. But be aware that only the scope of the connection providing Model ("master" Model instance) is responsible for cleaning up the connection. If this connection is disconnected and disposed before a slave instance is finished, the above methods for JCO.Client retrieval are again used for the master instance. This could finally result in using the defaultLogicalSystemName of the master instance.

If any but the last method above is used, the connection will be disconnected automatically at the end of the Model's scope, if the scope is other than NO_SCOPE. This means that the connection will be disconnected, when the lifetime of the Model ends. If automatic disconnection of the JCO.Client connection is not desired, use either the scope NO_SCOPE or use setJcoClient(null) before the scope ends. In both cases you are responsible for proper clean-up of the used connection.
Note that connections are a very expensive resource and can cause a server to crash if not maintained properly.

Version:

$Id: //tc/WebDynproRuntime/630_VAL_REL/src/_webdynpro_model_dynamicrfc/java/com/sap/tc/webdynpro/modelimpl/dynamicrfc/IWDDynamicRFCModel.java#1 $

Method Summary

void	disconnectIfAlive() checks if the connection is alive (connected) and disconnects it This will always guarantee, that the connection is no longer in use and all locks in the backend as well as the rollarea is released.
IWDDynamicRFCModel	getConnectionProvider() Returns this Model instance's connection provider (or null if none was assigned).
com.sap.mw.jco.JCO.Client	getCurrentlyUsedJcoClient() Returns the JCO.Client currently to be used for this Model instance.
com.sap.mw.jco.JCO.Client	getJcoClient() Returns the JCO.Client assigned explicitly to this Model instance or null if none has been assigned yet.
java.lang.String	getSystemName() Returns the logical system name as set by setSystemName(String).
void	setConnectionProvider(IWDDynamicRFCModel connProvider) Assigns this Model instance's connection provider.
void	setJcoClient(com.sap.mw.jco.JCO.Client client) Assigns this model instance's JCO.Client.
void	setSystemName(java.lang.String systemName) Assigns the logical system name used to retrieve connection information and credentials from the System Landscape Directory (SLD).

Methods inherited from interface com.sap.tc.webdynpro.progmodel.model.api.IWDModel

getModelInstanceId, getModelScope

Methods inherited from interface com.sap.tc.cmi.model.ICMIModel

associatedModelInfo, createModelObject, createModelObject

Methods inherited from interface com.sap.tc.webdynpro.progmodel.model.api.IWDModelRegistry

lookup, register, unregister, unregisterAll

Method Detail

setSystemName

public void setSystemName(java.lang.String systemName)

Assigns the logical system name used to retrieve connection information and credentials from the System Landscape Directory (SLD). Using this method allows to determine the JCO.Client for this Model by naming the logical system.

Returns:

name of logical system in System Landscape Directory.

getSystemName

public java.lang.String getSystemName()

Returns the logical system name as set by setSystemName(String). If no name has been set so far, the defaultLogicalSystemName as specified at design time is returned.

If none of the higher prioritized methods has been used, the return value of this method is used to retrieve connection information and credentials from the System Landscape Directory (SLD).

Returns:

name of logical system in System Landscape Directory.

setJcoClient

public void setJcoClient(com.sap.mw.jco.JCO.Client client)

Assigns this model instance's JCO.Client. The Client will be used as long as this model lives. The (maximum) lifetime of a Model instance is determined by the lifetime of its scope (e.g. TASK_SCOPE or APPLICATION_SCOPE).

Parameters:

client - JCO.Client to use to connect to backend.

getJcoClient

public com.sap.mw.jco.JCO.Client getJcoClient()

Returns the JCO.Client assigned explicitly to this Model instance or null if none has been assigned yet. This does not necessarily represent the JCO.Client to use for this model, e.g. if this model has been assigned a ConnectionProvider. See interface documentation for details.

Returns:

Jco Client.

setConnectionProvider

public void setConnectionProvider(IWDDynamicRFCModel connProvider)

Assigns this Model instance's connection provider. The connection provider will be used for retrieval of the JCO.Client from now on. If a JCO.Client was previously assigned, it will no longer be used, but will still be disconnected when the scope of this Model ends.

Parameters:

connProvider - DynamicRFCModel instance to use to retrive JCO.Client for connecting to backend.

getConnectionProvider

public IWDDynamicRFCModel getConnectionProvider()

Returns this Model instance's connection provider (or null if none was assigned). The connection provider is the Model instance to be used for retrieval of the JCO.Client. Note: The connection provider is not referenced directly but retrieved by looking it up in the WDModelFactory with the class, scope and instanceId as defined by the Model instance that was previously set as the connection provider.

Parameters:

connProvider - IWDDynamicRFCModel instance to use to retrieve the JCO.Client for connecting to backend.

getCurrentlyUsedJcoClient

public com.sap.mw.jco.JCO.Client getCurrentlyUsedJcoClient()
                                                    throws WDDynamicRFCException

Returns the JCO.Client currently to be used for this Model instance. The returned JCO.Client is determined by the following algorithm:

1. If a connection provider has been defined for this Model using setConnectionProvider(IWDDynamicRFCModel) and if that connection provider still has a connection (its scope did not end and the associated connection was not cleared), then the connection of the connection provider is returned.
2. If a JCO.Client has been set explicitly by calling setJcoClient(JCO.Client), then that client is returned.
3. If a logical system name has been defined using setSystemName(String) then the System Landscape Directory (SLD) is queried for the connection information and credentials stored under the given name. A JCO connection with the retrieved properties is created and returned. If accessing the SLD or querying the given name or creating the connection fails for any reason, a WDDynamicRFCException is thrown.
4. If none of the above applies, that is if none of the connection defining methods has been called, then the default logical system name - as declared at design time - is used to lookup connection information and credentials in the SLD and to create a connection from the retrieved data. As it was stated in the previous case, any error during SLD access or connection creation results in an WDDynamicRFCException being thrown.

Note that none of the options above implies the automatic connection of the returned JCO.Client .

Returns:

JCO.Client currently used to connect to backend.

disconnectIfAlive

public void disconnectIfAlive()

checks if the connection is alive (connected) and disconnects it This will always guarantee, that the connection is no longer in use and all locks in the backend as well as the rollarea is released. NOTE(1): This method only works for automatically attained connections as well as for non pooled connections, set via the API method setJcoClient(). If you have assigned a pooled JcoClient via setJcoClient(), then you must release the client yourself and call setJcoClient(null) NOTE(2): If this model is being provided a connection through a connectionProvider, then this connection will NOT be disconnected. It must then be disconnected through the connectionProvider directly