Think of a manned gate in a fence, to pass from one side to the other you need to pass through the gate. Where you are coming from and
where you are going is of no concern to the gate. The gatekeepers only concern is that your credentials are verified before allowing passage.
Concerns of and alternatives to this access model will not be discussed.
This sample code is a general purpose JDBC powered database gateway. Any system that can instantiate a Java object will be able to
connect to any database of choice, provided there is an appropriate JDBC driver, an available database and a user account in said database. SAS DATA
Step with javaobj is one such system.
The gateway is an RMI scheme involving a server process and a bound manager class that lives in the server process. A Java class operating
in a client mode obtains a reference to the remote manager by looking up (within the rmiregistry executor process) the instance that is bound to name
JDBC-GATEWAY-MANAGER. The manager class hands out integer handles to objects it instantiates and stores in hash tables (keyed by handle). The
manager class has methods for connecting to a database, creating a SQL statement, executing a SQL statement and examing returned Result Sets. Each
method requires a handle originally doled out.
A low order securuity scheme is implemented to deter 'handle scanning' by rogue agents. Each handle is a random number and attempts to use
a handle that was not doled out incurs a ½ second delay. The security could be improved by doling out an access code with each handle, and
requiring both the handle and access code when invoking methods of the gateway manager.
Since the manager only exposes methods that require an integer handle, client systems with no mechanism for java object persistence
can utilitize the manager by only remembering the integer handle between uses of the manager. In SAS, this means the handle can be maintained
in a macro variable as different DATA Steps execute. In UNIX, the handle could be maintained in a property file between invocations of the Java
program loader (this would be an atypical scenario in UNIX).
The implementation of the RMI scheme requires three classes
GatewayInterface - enumerates the methods that will be available to client mode classes.
GatewayManager - implements the methods of GatewayInterface
GatewayServer - class that is run to persist a bound instance of GatewayManager
Two additional classes are created by rmic, the rmi compiler; GatewayManger_skel and GatewayManager_stub. These classes are 'necessary
internal components' of any realized rmi scheme and should be ignored by most developers.
An adapter class was also written to allow a SAS javaobj to act as a client in the RMI scheme. Why ? The manager methods require integer
arguments, which SAS can not pass. Additionally, the manager can throw remote exceptions which javaobj can not gracefully handle. The adapter
provides the typecasting needed to invoke the methods of the manager (which itself realizes the gateway interface) and catches any exceptions
thrown.
This is a start. If you want to expand the gateway to have more functionality, you would list additional methods here and implement them
in GatewayManager. You would also have to implement adapter versions of the additional methods in DataStepGatewayAdapter
This class implements the methods listed in the interface. This is where the bulk of the work takes place. The manager instantiates
objects as requested and places them in a hash keyed by an Integer (the handle). The integer is returned to the client who must pass it back in order
to operate upon the object associated with the handle. The manager is essentially an adapter to parts of java.sql for systems unable to fully expose
the java experience.
This class is run to persist a GatewayManager. Java security settings, which will not be discussed, can be placed on the running of this
class to restrict the resources it uses.
The GatewayServer needs to be running separate from the clients that will access it. You can use this script to start the server when
running the DataStepGatewayAdapterTester. When using the Gateway from SAS, there is a macro you invoke to start the server.
The adapter was written to let javaobjs to interact with the GatewayManager. All the methods have numeric arguments as double, the only
numeric type javaobj can pass to java object methods. The adapter adds one method, getSasColumnType, which is not declared in GatewayInterface. The
method maps the variety of remote database types to the fundamental SAS data types of character or numeric.
This test unit instantiates a DataStepGatewayAdapter and works with it in the same way one would with a javaobj in a DATA Step. In order
to test the adapter, the server process needs to be running. Start the test using a command such as this: