com.sap.mw.jco

Class JCO.Server

java.lang.Object
  com.sap.mw.jco.JCO.Connection
      com.sap.mw.jco.JCO.Server

All Implemented Interfaces:

Cloneable, Runnable

Enclosing class:

JCO

public static class JCO.Server

extends JCO.Connection

implements Runnable

Encapsulates the basic JCO server functionality. Application programmers will extend this class and at least override the handleRequest() method to implement a specific server. e.g.:

  class MyServer extends JCO.Server {

      // Process incoming requests
      public void handleRequest(JCO.Function fct) {
          try {
             // Application specific processing goes here
          }
          catch(JCO.AbapException ex) {
               throw ex;
          }
          catch(Throwable t) {
               throw new JCO.AbapException("SYSTEM_FAILURE", t.getMessage());
          }
      }
  }
  

Note: If the server instance dispatches requests from an unicode system, it is necessary to set the addtional property jco.server.unicode to 1 and mark the destination in R/3 System (sm59) as unicode-enabled. Ensure to use in this case an unicode conform metadata repository.
Depending on the type of middleware layer loaded, the properties recognized by the JCO server may vary.
For com.sap.mw.jco.rfc.MiddlewareRFC, i.e. the default RFC layer, the supported properties are:

jco.server.gwhost	Gateway host
jco.server.gwserv	Gateway service (usually sapgwNN)
jco.server.progid	Program ID of the server
jco.server.trace	Enable/disable RFC trace (1 or 0)
jco.server.params	Arbitrary parameters for RFC library
jco.server.snc_myname	SNC name
jco.server.snc_qop	SNC level of security, 1 to 9
jco.server.snc_lib	Path to the SNC library
jco.server.unicode	Flags whether to connect in unicode mode (1 or 0)
jco.server.max_startup_delay	Maximum server startup delay time in seconds
jco.server.dsr	Enable/Disable dsr support (0 or 1)

Field Summary

static int	AUTHORIZATION_MODE_BASIC Authorization mode basic
static int	AUTHORIZATION_MODE_SNC Authorization mode SNC
static int	FUNCTION_MODEL Call void handleRequest(Function) method on incoming requests
protected com.sap.mw.jco.IMiddleware.IServer	m_middleware
static int	REQUEST_RESPONSE_MODEL Call Response handleRequest(Request) method on incoming requests

Fields inherited from class com.sap.mw.jco.JCO.Connection

attributes, codepage_converter, conn_object, conn_params, connection_cpc_mode, dsr_monitor, jarm_monitor, last_active_timestamp, num_received_bytes, num_sent_bytes, passport_bytes, pool, properties, rfc_handle, rfm_name, start_time, state, throughput, time_handle_request, time_middleware, time_total

Constructor Summary

	JCO.Server(Properties properties) Creates an instance of a server connection
	JCO.Server(Properties properties, IRepository repository) Creates an instance of a server connection
	JCO.Server(Properties properties, IServerThread thread, IRepository repository) Creates an instance of a server connection
	JCO.Server(String[][] params, IRepository repository) Creates an instance of a server using an array to specify the connection parameters.
	JCO.Server(String[] argv, IRepository repository) Creates an instance of a server using an arv array as passed by void main(String[] argv)
protected	JCO.Server(String gwhost, String gwserv, String progid) Creates an instance of a server connection Note: before this server can be used one must set the repository and thread !!!
	JCO.Server(String gwhost, String gwserv, String progid, IRepository repository) Creates an instance of a server connection
	JCO.Server(String gwhost, String gwserv, String progid, IServerThread thread, IRepository repository) Creates an instance of a server connection

Method Summary

void	abort(String message) Aborts the connection to the remote system, i.e.
protected void	beginCall() Notify about begin of call processing
protected boolean	checkAuthorization(String function_name, int authorization_mode, String authorization_partner, byte[] authorization_key) Called by the jni-layer to check for authorization in case of SNC usage for the server connection.
void	disconnect() Closes the connection to the remote system hardly and cleans up the connection context.
protected void	dispatchRequest(JCO.Function function) Called by the jni-layer after a request for a service has arrived.
protected void	endCall() Notify about end of call processing
JCO.Attributes	getAttributes() Returns the attributes object for this server.
int	getCallModel() Returns the call model which can be either JCO.Server.FUNCTION_MODEL or JCO.Server.REQUEST_RESPONSE_MODEL.
com.sap.jdsr.writer.DsrIPassport	getDsrPassport() Deprecated. only for internal use
protected JCO.Function	getFunction(String function_name) Called by the jni-layer after a request for a service has arrived.
String	getGWHost() Returns the gateway server
String	getGWServ() Returns the gateway service
protected com.sap.mw.jco.IMiddleware.IServer	getMiddlewareImplementation() Returns the middleware implementation Note: This method is for internal use only.
String	getProgID() Returns the program id
String[][]	getPropertyInfo() Returns the property info for the server
protected IRepository	getRepository() Returns the server's associated repository or null if not set
protected static com.sap.mw.jco.IMiddleware.IServer	getServerInterface() Creates a new middleware server object
byte	getState() Returns the server's state as a bit vector
Thread	getThread() Returns the thread this server is running in
boolean	getTrace() Returns whether trace is enabled or not.
void	handleRequest(JCO.Function function) Called after a request for a service has arrived.
void	handleRequest(JCO.Request request, JCO.Response response) Called after a request for a service has arrived.
boolean	isAlive() Checks whether the server is still alive
protected void	listen() Opens a server connection and listens for incoming calls
boolean	onCheckTID(String tid) This function will be invoked when a transactional RFC is being called from a SAP system.
void	onCommit(String tid) This function will be called after all RFC functions belonging to a certain transaction have been successfully completed.
void	onConfirmTID(String tid) This function will be called after the local transaction has been completed.
void	onRollback(String tid) This function will be called if an error in one of the RFC functions belonging to a certain transaction has occurred.
void	run() Implements the run method from the runnable interface
void	setCallModel(int call_model) Sets the call model which can be either JCO.Server.FUNCTION_MODEL or JCO.Server.REQUEST_RESPONSE_MODEL.
protected void	setProperty(String key, String value) Sets the property for the given key.
protected void	setRepository(IRepository repository) Sets the repository the server will be using to lookup incoming function calls
protected void	setState(byte state) Sets the state of the server and invokes the registered stateChangedListener
protected void	setThread(IServerThread thread) Sets the thread in which this server is running in
void	setTrace(boolean trace) Enables/disables trace
void	start() Starts or resumes execution of the server thread
void	stop() Forces the server and its underlying thread to stop execution The server can not be restarted after this method has been called.
void	suspend() Forces the server to temporarily stop execution.

Methods inherited from class com.sap.mw.jco.JCO.Connection

checkProperties, clone, finalize, getConnectionHandle, getProperties, getProperty, getThroughput, hideConnection, isValid, setThroughput

Methods inherited from class java.lang.Object

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

Field Detail

AUTHORIZATION_MODE_SNC

public static final int AUTHORIZATION_MODE_SNC

Authorization mode SNC

See Also:

Constant Field Values

AUTHORIZATION_MODE_BASIC

public static final int AUTHORIZATION_MODE_BASIC

Authorization mode basic

See Also:

Constant Field Values

FUNCTION_MODEL

public static final int FUNCTION_MODEL

Call void handleRequest(Function) method on incoming requests

See Also:

Constant Field Values

REQUEST_RESPONSE_MODEL

public static final int REQUEST_RESPONSE_MODEL

Call Response handleRequest(Request) method on incoming requests

See Also:

Constant Field Values

m_middleware

protected com.sap.mw.jco.IMiddleware.IServer m_middleware

Constructor Detail

JCO.Server

public JCO.Server(Properties properties)

Creates an instance of a server connection

Parameters:

properties - the connection parameters passed as a properties object

JCO.Server

public JCO.Server(Properties properties,
                  IRepository repository)

Creates an instance of a server connection

Parameters:

properties - the connection parameters passed as a properties object

repository - the repository used by the server to lookup the definitions of an incoming function call

Since:

JCo 1.1.04

JCO.Server

public JCO.Server(Properties properties,
                  IServerThread thread,
                  IRepository repository)

Creates an instance of a server connection

Parameters:

properties - the connection parameters passed as a properties object

thread - the thread this server is running in

repository - the repository used by the server to lookup the definitions of an incoming function call

Since:

JCo 2.0

JCO.Server

public JCO.Server(String[][] params,
                  IRepository repository)

Creates an instance of a server using an array to specify the connection parameters. Each item in the array is a name/value pair where the first element is the name and the second is the value associated with the name, e.g.

     static String[][] login_params  = {
        { "gwhost" ,   "bin20"     },
        { "gwserv"   , "gwbin20"   },
        { "progid" ,   "PROGRAM01" },
     };
 

Parameters:

params - the connection parameters as an two-dimemsional array

repository - the repository used by the server to lookup the definitions of an incoming function call

JCO.Server

public JCO.Server(String[] argv,
                  IRepository repository)

Creates an instance of a server using an arv array as passed by void main(String[] argv)

Parameters:

argv - the array of arguments as passed by void main(String[] argv)

repository - the repository used by the server to lookup the definitions of an incoming function call

Since:

1.1.03

JCO.Server

public JCO.Server(String gwhost,
                  String gwserv,
                  String progid,
                  IRepository repository)

Creates an instance of a server connection

Parameters:

gwhost - the gateway host

gwserv - the gateway service number (usually sapgwNN)

progid - the program id

repository - the repository used by the server to lookup the definitions of an incoming function call

JCO.Server

public JCO.Server(String gwhost,
                  String gwserv,
                  String progid,
                  IServerThread thread,
                  IRepository repository)

Creates an instance of a server connection

Parameters:

gwhost - the gateway host

gwserv - the gateway service number

progid - the program id

thread - the thread this server is running in

repository - the repository used by the server to lookup the definitions of an incoming function call

JCO.Server

protected JCO.Server(String gwhost,
                     String gwserv,
                     String progid)

Creates an instance of a server connection Note: before this server can be used one must set the repository and thread !!! This constructor normally is only used by derived classes.

Parameters:

gwhost - the gateway host

gwserv - the gateway service number

progid - the program id

Method Detail

getServerInterface

protected static com.sap.mw.jco.IMiddleware.IServer getServerInterface()

Creates a new middleware server object

setThread

protected void setThread(IServerThread thread)

Sets the thread in which this server is running in

getRepository

protected IRepository getRepository()

Returns the server's associated repository or null if not set

Returns:

the server's repository or null

Since:

2.0

setRepository

protected void setRepository(IRepository repository)

Sets the repository the server will be using to lookup incoming function calls

getMiddlewareImplementation

protected com.sap.mw.jco.IMiddleware.IServer getMiddlewareImplementation()

Returns the middleware implementation Note: This method is for internal use only. Do not use in application programs.

Returns:

the implementation of middleware layer currently used

getPropertyInfo

public final String[][] getPropertyInfo()

Returns the property info for the server

Overrides:

getPropertyInfo in class JCO.Connection

Returns:

the property info

setProperty

protected void setProperty(String key,
                           String value)

Sets the property for the given key. If the passed value is null the property will be removed from the property list.

Overrides:

setProperty in class JCO.Connection

setCallModel

public void setCallModel(int call_model)

Sets the call model which can be either JCO.Server.FUNCTION_MODEL or JCO.Server.REQUEST_RESPONSE_MODEL. Depending on the call model either the void handleRequest(JCO.Function function) or tje method void handleRequest(JCO.Request, JCO.Response) will be called on incoming requests. The default is calling void handleRequest(Function function)

Parameters:

call_model - the call model which this server uses

See Also:

getCallModel()

getCallModel

public int getCallModel()

Returns the call model which can be either JCO.Server.FUNCTION_MODEL or JCO.Server.REQUEST_RESPONSE_MODEL.

Since:

JCo 2.0

See Also:

setCallModel(int), handleRequest(JCO.Function), handleRequest(JCO.Request, JCO.Response)

setState

protected void setState(byte state)

Sets the state of the server and invokes the registered stateChangedListener

Overrides:

setState in class JCO.Connection

Parameters:

state - the new state of the server

See Also:

getState()

getState

public byte getState()

Returns the server's state as a bit vector

Overrides:

getState in class JCO.Connection

Returns:

the state of the server as a bit vector

Flag	Description
JCO.STATE_STOPPED	The server has been stopped
JCO.STATE_STARTED	The server has been started
JCO.STATE_LISTENING	The server is listening for incoming requests
JCO.STATE_BUSY	The server is currently processing an incoming request
JCO.STATE_TRANSACTION	The server incoming request is a transaction

getThread

public Thread getThread()

Returns the thread this server is running in

Returns:

the thread this server is running in

getAttributes

public final JCO.Attributes getAttributes()

Returns the attributes object for this server.

Specified by:

getAttributes in class JCO.Connection

Returns:

the attributes object for this server.

Throws:

JCO.Exception - thrown if the attributes could not be retrieved.

See Also:

JCO.Attributes

getGWHost

public final String getGWHost()

Returns the gateway server

Returns:

the gateway server

getGWServ

public final String getGWServ()

Returns the gateway service

Returns:

the gateway service

getProgID

public final String getProgID()

Returns the program id

Returns:

the program id

getTrace

public final boolean getTrace()

Returns whether trace is enabled or not.

Overrides:

getTrace in class JCO.Connection

Returns:

true if trace is enabled, false otherwise

setTrace

public final void setTrace(boolean trace)

Enables/disables trace

Overrides:

setTrace in class JCO.Connection

Parameters:

trace - if true enables the trace and disables it otherwise.

getDsrPassport

public com.sap.jdsr.writer.DsrIPassport getDsrPassport()

Deprecated. only for internal use

get dsr passport for last server request

Returns:

dsr passport

Throws:

JCO.Exception - if DSR library wasn't found in classpath or dsp passport wasn't send by partner side

disconnect

public void disconnect()

Closes the connection to the remote system hardly and cleans up the connection context.
Note: This function is for internal use only. Do not use in application programs. For a safe server shutdown please use stop-method instead. Calling this method on a running server can cause RFC errors and/or memory access violations.

Specified by:

disconnect in class JCO.Connection

See Also:

stop()

abort

public void abort(String message)

Aborts the connection to the remote system, i.e. tries to send a final message to the host before it disconnects.

Specified by:

abort in class JCO.Connection

Parameters:

message - the final message which will be sent to the remote system.

start

public void start()

Starts or resumes execution of the server thread

stop

public void stop()

Forces the server and its underlying thread to stop execution The server can not be restarted after this method has been called. To temporarily stop a server use suspend() instead.

See Also:

suspend()

suspend

public void suspend()

Forces the server to temporarily stop execution. The server can be restarted using the start() method.

See Also:

start()

run

public void run()

Implements the run method from the runnable interface

Specified by:

run in interface Runnable

isAlive

public boolean isAlive()

Checks whether the server is still alive

Specified by:

isAlive in class JCO.Connection

Returns:

true if the server is alive, false otherwise

listen

protected void listen()

Opens a server connection and listens for incoming calls

getFunction

protected JCO.Function getFunction(String function_name)

Called by the jni-layer after a request for a service has arrived. Returns the function for the specified name.

Parameters:

function_name - the name of the function that has been called

Returns:

the function for the specified name or null if not found

Throws:

JCO.Exception - if either the specified function or one of the associated data structures could not be retrieved from the repository.

checkAuthorization

protected boolean checkAuthorization(String function_name,
                                     int authorization_mode,
                                     String authorization_partner,
                                     byte[] authorization_key)

Called by the jni-layer to check for authorization in case of SNC usage for the server connection.
Derived servers will override this function to actually implement the authorization handling. The method has to return true if the the request should be accepted and it returns false if the caller is not authorized to invoke the function.
Note:This method will be invoked only if SNC is used on the server connection.

Parameters:

function_name - the function that has been called by a remote client

authorization_mode - the mode of the authorization:

Mode	Description
AUTHORIZATION_SNC	Secure Network compliant authorization
AUTHORIZATION_BASIC	Basic authorization

authorization_partner - the partner (system) name where the request comes from

authorization_key - the authorization key as binary data depending on the mode

Returns:

true if the request should be accepted and false otherwise.

dispatchRequest

protected void dispatchRequest(JCO.Function function)
                        throws Exception

Called by the jni-layer after a request for a service has arrived.
The default implementation just calls handleRequest() Derived servers can override this to to a more elaborate dispatching.

Parameters:

function - the function that has been called by a remote client

Throws:

Exception

handleRequest

public void handleRequest(JCO.Function function)
                   throws Exception

Called after a request for a service has arrived.
Derived servers will override this function to actually implement a specific request handling.
When this routine exits without any pending exception the output parameters and tables will be sent back to the calling SAP system. If an exception has been thrown and is still pending, JCo handles it according to the following rules:
a) The exception is a JCO.AbapException or JCO.J2EEAbapException or the message text of the exception is the name of one of the exceptions specified in the call interface of the ABAP module. JCo will raise a corresponding ABAP exception in such a case and pass the exception's message text into the SAP system variables SY-MSGV1 to SY-MSGV4.
b) The exception is not a JCO.AbapException and the message text does not correspond to one of the ABAP exceptions. In this case JCo will raise a system exception in the calling SAP system.

Parameters:

function - the function that has been called by a remote client

Throws:

Exception

handleRequest

public void handleRequest(JCO.Request request,
                          JCO.Response response)
                   throws Exception

Called after a request for a service has arrived.
Derived servers will override this function to actually implement a specific request handling.
When this routine exits without any pending exception the output parameters and tables will be sent back to the calling SAP system. If an exception has been thrown and is still pending, JCo handles it according to the following rules:
a) The exception is a JCO.AbapException or JCO.J2EEAbapException or the message text of the exception is the name of one of the exceptions specified in the call interface of the ABAP module. JCo will raise a corresponding ABAP exception in such a case and pass the exception's message text into the SAP system variables SY-MSGV1 to SY-MSGV4.
b) The exception is not a JCO.AbapException and the message text does not correspond to one of the ABAP exceptions. In this case JCo will raise a system exception in the calling SAP system.

Parameters:

request - the request container filled with the data from the calling program

response - the response container whose contents will be send back to the calling SAP system.

Throws:

Exception

onCheckTID

public boolean onCheckTID(String tid)

This function will be invoked when a transactional RFC is being called from a SAP system. The function has to store the TID in permanent storage and return true. The method has to return false if the a transaction with this ID has already been processed. Throw an exception if anything goes wrong. The transaction processing will be aborted thereafter.
Derived servers must override this method to actually implement the transaction ID management.

Parameters:

tid - the transaction ID

Returns:

true if the ID is valid and not in use, false otherwise

onConfirmTID

public void onConfirmTID(String tid)

This function will be called after the local transaction has been completed. All resources associated with this TID can be released.
Derived servers must override this method to actually implement the transaction ID management.

Parameters:

tid - the transaction ID

onCommit

public void onCommit(String tid)

This function will be called after all RFC functions belonging to a certain transaction have been successfully completed.
Derived servers can override this method to locally commit the transaction.

Parameters:

tid - the transaction ID

onRollback

public void onRollback(String tid)

This function will be called if an error in one of the RFC functions belonging to a certain transaction has occurred.
Derived servers can override this method to locally rollback the transaction.

Parameters:

tid - the transaction ID

beginCall

protected void beginCall()

Notify about begin of call processing

Specified by:

beginCall in class JCO.Connection

endCall

protected void endCall()

Description copied from class: JCO.Connection

Notify about end of call processing

Specified by:

endCall in class JCO.Connection