com.sap.conn.jco.server
Interface JCoServer


public interface JCoServer

The JCoServer interface provides access to the public APIs in the JCo server implementation. Applications implementing server applications use the JCoServerFactory to create an instance of the JCoServer.
Once the server instance is created, the application can customize and then start it. The connections will be opened asynchronously.

The JCoServer provides the following features:

The JCo distribution contains an example StepByStepServer.java, which is covering the basic topics. StatefulServerExample.java covers the implementation of stateful requests.

See Also:
JCoServerFactory.getServer(String)

Method Summary
 void addServerErrorListener(JCoServerErrorListener listener)
          Adds a new listener to the list of error listeners.
 void addServerExceptionListener(JCoServerExceptionListener listener)
          Adds a new listener to the list of exception listeners.
 void addServerStateChangedListener(JCoServerStateChangedListener listener)
          Adds a new listener to the list of state change listeners.
 JCoServerCallHandlerFactory getCallHandlerFactory()
          Returns the call handler factory of this server.
 int getConnectionCount()
          Returns the initial connection count for this server.
 java.lang.String getGatewayHost()
          Returns the gateway host as defined by the server configuration.
 java.lang.String getGatewayService()
          Returns the gateway service (or port) as defined by the server configuration.
 JCoServerMonitor getMonitor()
          Returns a monitor instance describing the server threads and connections that have been created by this server instance.
 java.lang.String getMySncName()
          Returns the SNC name as defined by the server configuration.
 java.lang.String getProgramID()
          Returns the program id as defined by the server configuration.
 java.lang.String getProperty(java.lang.String key)
          Returns the value for a property defined by the server configuration.
 JCoRepository getRepository()
          Returns the default repository instance used by this server instance.
 JCoRepository getRepository(JCoServerContextInfo serverContext)
          Returns the repository instance used by this server instance for the specified request context.
 java.lang.String getRepositoryDestination()
          Returns the repository destination name for obtaining the default repository.
 java.lang.String getSAPRouterString()
          Returns the SAProuter string as defined by the server configuration.
 JCoServerSecurityHandler getSecurityHandler()
          Returns the security handler instance of this server.
 JCoServerThreadStarter getServerThreadStarter()
          Returns the thread starter instance of this server.
 java.lang.String getSncLibrary()
          Returns the path to the SNC library as defined by the server configuration.
 boolean getSncMode()
          Returns true if the server is configured to use an SNC connection.
 int getSncQOP()
          Returns the quality of protection level of SNC as defined by the server configuration.
 JCoServerState getState()
          Returns the current state of this server.
 JCoThroughput getThroughput()
          Returns the throughput instance.
 JCoServerTIDHandler getTIDHandler()
          Returns the TID handler instance of this server.
 JCoServerUnitIDHandler getUnitIDHandler()
          Returns the unit ID handler instance of this server.
 boolean isValid()
          Returns true if the corresponding server configuration was neither changed nor removed, false otherwise.
 void release()
          Releases all resources allocated by the server instance.
 void removeServerErrorListener(JCoServerErrorListener listener)
          Removes a listener from the list of error listeners.
 void removeServerExceptionListener(JCoServerExceptionListener listener)
          Removes a listener from the list of exception listeners.
 void removeServerStateChangedListener(JCoServerStateChangedListener listener)
          Removes a listener from the list of state change listeners.
 void removeThroughput()
          Removes the throughput instance from this server.
 void setCallHandlerFactory(JCoServerCallHandlerFactory callHandlerFactory)
          Sets the call handler factory that will be used by the JCo runtime to get a handler instance if a remote call is invoked.
 void setConnectionCount(int count)
          Sets the number of registered connections managed by this server instance.
This API has to be invoked before the start of the server and may be invoked at runtime.
 void setRepository(JCoDestination destination)
          Sets the destination instance which is used for obtaining the default repository for querying RFC metadata.
 void setRepository(JCoRepository repository)
          Sets the default repository instance which is being used for querying RFC metadata.
 void setRepository(java.lang.String sID, java.lang.String client, JCoDestination destination)
          Sets the repository destination instance for incoming RFC calls from the system with the system ID sID and - if defined - with the appropriate client.
 void setRepository(java.lang.String sID, java.lang.String client, JCoRepository repository)
          Sets the repository instance for incoming RFC calls from the system with the system ID sID and - if defined - with the appropriate client.
 void setSecurityHandler(JCoServerSecurityHandler securityHandler)
          Sets the security handler for this server instance.
 void setServerThreadStarter(JCoServerThreadStarter starter)
          Sets a special instance for the task of starting new threads for this server.
 void setThroughput(JCoThroughput throughput)
          Sets the throughput instance for measuring the RFC requests dispatched by this server.
 void setTIDHandler(JCoServerTIDHandler tidHandler)
          Sets the TID handler to be used by this server for incoming transactional and queued RFC requests.
 void setUnitIDHandler(JCoServerUnitIDHandler unitIDHandler)
          Sets the unit ID handler to be used by this server for incoming background RFC requests.
 void start()
          Starts the server.
The server will open the specified number of connections.
 void stop()
          Stops the server.
All connections will be closed, cached requests will not be processed and aborted.
 

Method Detail

start

void start()
Starts the server.
The server will open the specified number of connections.

See Also:
setConnectionCount(int)

stop

void stop()
Stops the server.
All connections will be closed, cached requests will not be processed and aborted.

See Also:
setConnectionCount(int)

setConnectionCount

void setConnectionCount(int count)
Sets the number of registered connections managed by this server instance.
This API has to be invoked before the start of the server and may be invoked at runtime. The valid value range is [1..100].

Note: In most scenarios 2 connections are enough for a server to serve business calls and 1 connection that is used for technical/administrative purposes.

Parameters:
count - number of registered connections to manage by the server instance

getConnectionCount

int getConnectionCount()
Returns the initial connection count for this server.

Returns:
connection count

release

void release()
Releases all resources allocated by the server instance. This method can be used only after all server worker threads have been stopped.

Throws:
JCoRuntimeException - in case some workers are still running

getRepository

JCoRepository getRepository()
Returns the default repository instance used by this server instance.

Returns:
server's default repository

getRepository

JCoRepository getRepository(JCoServerContextInfo serverContext)
Returns the repository instance used by this server instance for the specified request context.

Parameters:
serverContext - request context
Returns:
server's repository
Since:
JCo 3.0.5

setRepository

void setRepository(JCoDestination destination)
Sets the destination instance which is used for obtaining the default repository for querying RFC metadata. A previously defined default repository that has been set by calling setRepository(JCoRepository) will be overwritten by this method.

Parameters:
destination - a destination being used for obtaining the default repository
Since:
JCo 3.0.11

setRepository

void setRepository(JCoRepository repository)
Sets the default repository instance which is being used for querying RFC metadata. A previously defined repository destination that has been set by calling setRepository(JCoDestination) will be overwritten by this method.

Parameters:
repository - either a custom repository or a repository connected to an ABAP server

setRepository

void setRepository(java.lang.String sID,
                   java.lang.String client,
                   JCoDestination destination)
                   throws JCoRuntimeException
Sets the repository destination instance for incoming RFC calls from the system with the system ID sID and - if defined - with the appropriate client. If the client is not relevant it may be null. If no matching SID and client combination is defined, the repository for the specified SID only will be used. If also no SID is defined, the current default repository will be used for processing the appropriate RFC call.
An already defined corresponding repository rule that has been set before by calling setRepository(String, String, JCoRepository) will be overwritten by this method.

Parameters:
sID - system ID of the SAP ABAP system containing exactly 3-letters
client - null or the client containing exactly 3 digits
destination - destination instance to be used for obtaining a repository if sID and client are matching
Throws:
JCoRuntimeException - is thrown if sID or client is illegal.
Since:
JCo 3.0.11

setRepository

void setRepository(java.lang.String sID,
                   java.lang.String client,
                   JCoRepository repository)
                   throws JCoRuntimeException
Sets the repository instance for incoming RFC calls from the system with the system ID sID and - if defined - with the appropriate client. If the client is not relevant it may be null. If no matching SID and client combination is defined, the repository for the specified SID only will be used. If also no SID is defined, the current default repository will be used for processing the appropriate RFC call.
An already defined corresponding repository destination rule that has been set before by calling setRepository(String, String, JCoDestination) will be overwritten by this method.

Parameters:
sID - system ID of the SAP ABAP System containing exactly 3-letters
client - null or the client containing exactly 3 digits
repository - repository instance to be used if sID and client are matching
Throws:
JCoRuntimeException - is thrown if sID or client is illegal.
Since:
JCo 3.0.5

getGatewayHost

java.lang.String getGatewayHost()
Returns the gateway host as defined by the server configuration.

Returns:
gateway host string

getGatewayService

java.lang.String getGatewayService()
Returns the gateway service (or port) as defined by the server configuration.

Returns:
gateway service string

getSAPRouterString

java.lang.String getSAPRouterString()
Returns the SAProuter string as defined by the server configuration. The SAProuter string will be used to locate the gateway. The SAProuter string contains one or more routers with the follow format:
/H/<host name>[/S/<port>][/W/<password>]

Returns:
SAProuter string

getProgramID

java.lang.String getProgramID()
Returns the program id as defined by the server configuration.

Returns:
program id as string

getSncMode

boolean getSncMode()
Returns true if the server is configured to use an SNC connection.

Returns:
true if SNC is on

getMySncName

java.lang.String getMySncName()
Returns the SNC name as defined by the server configuration.

Returns:
SNC name string

getSncQOP

int getSncQOP()
Returns the quality of protection level of SNC as defined by the server configuration.

Returns:
QOP level of SNC

getSncLibrary

java.lang.String getSncLibrary()
Returns the path to the SNC library as defined by the server configuration.

Returns:
path to the SNC library

getProperty

java.lang.String getProperty(java.lang.String key)
Returns the value for a property defined by the server configuration.

Parameters:
key - property key for looking up the property value to return
Returns:
value for the specified property key

getRepositoryDestination

java.lang.String getRepositoryDestination()
Returns the repository destination name for obtaining the default repository.

Returns:
the specified default repository destination name

setCallHandlerFactory

void setCallHandlerFactory(JCoServerCallHandlerFactory callHandlerFactory)
Sets the call handler factory that will be used by the JCo runtime to get a handler instance if a remote call is invoked.

A factory for the call handlers is required. The server instance cannot be started unless a factory has been set.
callHandlerFactory must be an instance of JCoServerRequestHandlerFactory or JCoServerFunctionHandlerFactory, otherwise a JCoRuntimeException will be thrown.

Parameters:
callHandlerFactory - call handler factory to be used by the server
See Also:
DefaultServerHandlerFactory

getCallHandlerFactory

JCoServerCallHandlerFactory getCallHandlerFactory()
Returns the call handler factory of this server.

Returns:
the call handler factory used by this server

setTIDHandler

void setTIDHandler(JCoServerTIDHandler tidHandler)
Sets the TID handler to be used by this server for incoming transactional and queued RFC requests.

RFC requests being sent "in background task" (tRFC) or with the queue extension (qRFC) are identified by a unique TID (Transaction ID).
To ensure proper TID handling and to separate the TID handling from the application logic, the method handling with TIDs are gathered in the JCoServerTIDHandler interface. Each application dispatching tRFC or qRFC calls has to implement and set an appropriate JCoServerTIDHandler instance.

Parameters:
tidHandler - instance providing the TID handling

getTIDHandler

JCoServerTIDHandler getTIDHandler()
Returns the TID handler instance of this server.

Returns:
the TID handler used by this server, or null if none is set

setUnitIDHandler

void setUnitIDHandler(JCoServerUnitIDHandler unitIDHandler)
Sets the unit ID handler to be used by this server for incoming background RFC requests.

RFC requests being sent "in background unit" (bgRFC) are identified by a unique unit ID.
The treatment of unit IDs is similar to the TID handling. To ensure that the application is aware of the differences in the TID and unit ID handling, the unit ID handling is defined separately by the interface JCoServerUnitIDHandler. Each application dispatching bgRFC calls has to implement and set an appropriate JCoServerUnitIDHandler instance.

Parameters:
unitIDHandler - instance providing the unit ID handling

getUnitIDHandler

JCoServerUnitIDHandler getUnitIDHandler()
Returns the unit ID handler instance of this server.

Returns:
the unit ID handler used by this server, or null if none is set

setSecurityHandler

void setSecurityHandler(JCoServerSecurityHandler securityHandler)
Sets the security handler for this server instance.

The security handler will be invoked by the JCo runtime to check the permissions of the user who initiated the RFC request.

Note: Once the security handler is set it is not possible to change it due to security reasons. The only way to change the implementation of the security handler is to create and start another server instance.

Parameters:
securityHandler - security handler to be used by the server

getSecurityHandler

JCoServerSecurityHandler getSecurityHandler()
Returns the security handler instance of this server.

Returns:
the security handler used by this server, or null if none is set

setServerThreadStarter

void setServerThreadStarter(JCoServerThreadStarter starter)
Sets a special instance for the task of starting new threads for this server.

In some runtime environments starting new threads via Thread.start() is not allowed and may be done with using special APIs only. For this case the application can provide its own implementation for starting new server threads.

Parameters:
starter - instance for starting new server worker threads

getServerThreadStarter

JCoServerThreadStarter getServerThreadStarter()
Returns the thread starter instance of this server.

Returns:
the thread starter instance used by this server, or null if none is set

addServerErrorListener

void addServerErrorListener(JCoServerErrorListener listener)
Adds a new listener to the list of error listeners.

If a listener is added to the list of error listeners during firing an event, it won't be notified about this event.

Parameters:
listener - the error listener to add
See Also:
removeServerErrorListener(com.sap.conn.jco.server.JCoServerErrorListener)

addServerExceptionListener

void addServerExceptionListener(JCoServerExceptionListener listener)
Adds a new listener to the list of exception listeners.

If a listener is added to the list of exception listeners during firing an event, it won't be notified about this event.

Parameters:
listener - the listener to add
See Also:
removeServerExceptionListener(com.sap.conn.jco.server.JCoServerExceptionListener)

addServerStateChangedListener

void addServerStateChangedListener(JCoServerStateChangedListener listener)
Adds a new listener to the list of state change listeners.

If a listener is added to the list of state change listeners during firing an event, it won't be notified about this event.

Parameters:
listener - the listener to add
See Also:
removeServerStateChangedListener(com.sap.conn.jco.server.JCoServerStateChangedListener)

removeServerErrorListener

void removeServerErrorListener(JCoServerErrorListener listener)
Removes a listener from the list of error listeners.

If a listener is removed from the list of error listeners during firing an event, it will be still notified about this event.

Parameters:
listener - the listener to remove
See Also:
addServerErrorListener(com.sap.conn.jco.server.JCoServerErrorListener)

removeServerExceptionListener

void removeServerExceptionListener(JCoServerExceptionListener listener)
Removes a listener from the list of exception listeners.

If a listener is removed from the list of exception listeners during firing an event, it will be still notified about this event.

Parameters:
listener - the listener to remove
See Also:
addServerExceptionListener(com.sap.conn.jco.server.JCoServerExceptionListener)

removeServerStateChangedListener

void removeServerStateChangedListener(JCoServerStateChangedListener listener)
Removes a listener from the list of state change listeners.

If a listener is removed from the list of state change listeners during firing an event, it will be still notified about this event.

Parameters:
listener - the listener to remove
See Also:
addServerStateChangedListener(com.sap.conn.jco.server.JCoServerStateChangedListener)

setThroughput

void setThroughput(JCoThroughput throughput)
Sets the throughput instance for measuring the RFC requests dispatched by this server. A previously defined throughput instance will be overwritten.

Parameters:
throughput - the throughput instance for storing the performance data

getThroughput

JCoThroughput getThroughput()
Returns the throughput instance.

Returns:
the throughput instance

removeThroughput

void removeThroughput()
Removes the throughput instance from this server. The measuring will be deactivated.


getMonitor

JCoServerMonitor getMonitor()
Returns a monitor instance describing the server threads and connections that have been created by this server instance.

Returns:
a monitor instance

getState

JCoServerState getState()
Returns the current state of this server.

Returns:
the current state of this server

isValid

boolean isValid()
Returns true if the corresponding server configuration was neither changed nor removed, false otherwise.

Returns:
true if server configuration was neither changed nor removed
Since:
JCo 3.0.7


Copyright © 2008-2016 SAP SE. All Rights Reserved.