Network Server accepts connections from DRDA clients, translates incoming DRDA Requests into embedded JDBC calls and then translates results back into DRDA for return to the client. Below is a summary of the implementation.
Classes Summary
NetworkServerControlImpl - This class implements methods used by the public API and main. It's functions include:
Launching a ConnectionThread to accept incomming connections.
Manaintaining a list of sessions, a queue of Sessions waiting for free thread and free list of DRDAConnections which are available for reuse.
Handling non-DRDA proprietary protocol requests (e.g. turning tracing on/off)
ClientThread - A single instance of this thread is launced to accept connections. It is responsible for
accepting connections
creating a new Sessions and adding them to the session table.
Starting a DRDAConnThread (either one from the free list or a new one) or putting the sessions waiting for a thread if maxThreads is exceeded.
ApplicationRequester - this contains information about a particular application requester(e.g, type, version, level of protocol it supports).
Session - this contains information about the client session, (e.g., client socket, AppRequester , current state, etc). It refers to a Database object which contains information about the database connection.
Database - this contains info about the database connection, prepared statements etc. It contains a hash table of DRDAStatements that are keyed by the package name and section number for the statement. Prepared statements are identified in the DRDA protocol by a package and section number.
DRDAStatement - This contains the Statement and all of its DRDA related information as well as the statement's DRDAResultSets which contain result set information. DRDA type information for the parameter metadata is also contained in this class. (It would be good to break it out). For JCC each statement has its isolation level encoded in the package name, and the isolation level is asssociated with the statement instead of the the connection. The isoloation level for the statement will be set accordingly if the client is JCC. DerbyClient sets the isololation on the connection per the JDBC spec and does not use the statement isolation level.
DRDAResultSet - Contains the result set and related metadata and DRDA type information. There is a package name and section number associated with the ResultSet as well. If a statement has only a single ResultSet the package and section number is the same as the statement. Additional ResultSets (created by stored procedures) are assigned a different section number by the server.
DRDAConnThread - This is the main workhorse for the DRDA connections. It sets up the input streams, creates instances of the DDMReader and DDMWriter classes and processes DRDA commands. Most of the DRDA protocol is in this class.
DDMReader - This class contains the utility methods for reading the incoming DRDA protocol and command protocol.
DDMWriter - This class contains the utility methods for writing the outgoing DRDA protocol and command protocol.
DRDAProtocolException - This class handles DRDA protocol errors.
EXTDTAInputStream - An input stream for externalized data (large object).
CcsidManager - This is an abstract class for performing character conversions.
EbcdicCcsidManager- This class converts from EBCDIC to Java Unicode. The DDM parameters are transmitted in EBCDIC and need to be converted to Java Unicode.
CodePoint- static values for DDM Codepoints. These are predefined values used in the DRDA protocol.
CodePointNameTable - hash table with codepoint names, used to produce tracing information.
DssTrace - provides server side tracing for the DRDA protocol.
FdocaConstants -FDOCA (Formatted Data Object Content Architecture) describes the layout and data types of the data being transmitted between the requester and server. This class defines statics for the constant values.
SQLTypes - DRDA describes SQL Types for the data types being transmitted. This class defines statics for the constant values.
EncryptionManager- routines for decrypting userid and password to handle encrypted userid and password security. This requires IBM JCE
SignedBinary - this is a conversion class that translates the incoming values from the client into the correct byte order. The DRDA protocol requires that the receiver of data translates the data into it's format (i.e., the writer writes data in its own format). Data has to be converted from the writer format to the local format.
Scheduling
The scheduling algorithm used is first in first out. When a client session connects to the server, the server checks to see if there are any DRDAConnThreads which are free to handle the session. If there are, it notifies the thread. If there are no available threads and we haven't reached the maximum number of connection threads we can have, the server creates a new thread with the session information. If we have already reached the maximum number of connection threads, the server places the session on a run queue for the next available thread.
How long a thread works on a particular session depends on the value of the timeslice. If timeslice is 0, the thread works on the session until the session ends. If the timeslice is greater than 0, the thread checks the amount of time it has spent on the session after each complete communication once the session has been initiated. A complete communication consists of a packet from the client and the return from the server. For example, for an execute immediate of a create table command, the packet from the client would include the create table command and a commit. The return from the server would be information about the result of the command. For a cursor, each fetch would represent a separate communication.
A timeout of the timeslice is set on the client socket so that the connection thread won't be blocked for more than the timeslice by an idle client.
Coordinating information between Server and Connection Threads
Several commands change information needed by the connection threads. For example, timeslice can be changed. This is handled by keeping a copy of the value in the connection thread. If the value is changed, the command changing the value is responsible for changing the value in the thread's copy. The result of this is that instead of one synchronization point in the server which all threads will block on to read, each thread has a copy which it can separately sync on.
Command Protocol
The command protocol is used to send commands such as shutdown, turn tracing on, etc. to a running network server. The client sends:
4 bytes - String CMD:
2 bytes - Protocol version
1 byte - command
n bytes - parameters for the command
The server returns:
1 byte - command result, 0 - OK, 1 - error
1 byte - number of messages
2 bytes - length of message (or message key)
n bytes - message or message key
1 byte - number of parameters to message
{2 bytes - length of parameter
n bytes - parameter} for each parameter
Note, the 3rd byte of the command header must not be 'D0' to distinquish it from DRDA DSS structures.
The protocol for the parameters for each command is in the javadoc for NetworkServerControlImpl.
The processing routine is synchronized so that multiple threads don't clobber each other. This means that configuration commands will be serialized. This shouldn't be a problem since they should be fairly rare.
DRDA Protocol
The DRDA protocol is described at great length in the DRDA Reference manuals. DRDA Protocol is divided into three layers corresponding to the DDM three-tier architecture. For each layer, their is a DSS (Data Stream Structure) defined.
Layer A Communications management services
Layer B Agent services
Layer C Data management services
At layer A are request, reply and data correlation, structure chaining, continuation or termination of chains when errors are detected, interleaving and multi-leaving request, reply, and data DSSs for multitasking environments. For TCP/IP, the format of the DDM envelope is
2 bytes Length of the data
1 byte 'D0' - indicates DDM data
1 byte DDM format byte(DSSFMT) - type of DSS(RQSDSS,RPYDSS), whether it is chained, information about the next chained DSS
2 bytes request correlation identifier
The correlation identifier ties together a request, the request data and the reply. In a chained DSS, each request has a correlation identifier which is higher than the previous request (all correlation identifiers must be greater than 0).
At layer B are object mapping, object validation and command routing. Layer B objects with data 5 bytes less than 32K bytes consist of
2 bytes Length
2 bytes Type of the object (code point)
Object data
Object data is either SCALAR or COLLECTION data.
Scalar data consists of a string of bytes formatted as the class description of the object required. Collections consist of a set of objects in which the entries in the collection are nested within the length/ code point of the collection.
Layer B objects with data >=32763 bytes long format is
2 bytes Length - length of class, length, and extended total length fields (high order bit set, indicating >=32763)
2 bytes Type of the object (code point)
n bytes Extended total length - length of the object (n = Length – 4)
Object data
Some of the objects in the collections are required and some are optional. To handle this, a required array is created for each command with optional objects with the required codepoints and each element is zeroed as the required objects are found. A check is done to see if there are any required objects missing and an error message is produced indicating the missing codepoints if some have not been sent.
Packages
In DRDA, dynamic SQL is bound to predefined packages. Since Derby doesn't support packages, PACKAGE messages will be handled entirely in the network server.The network server will just validate the protocol and "pretend" to execute the bind command.
*This document was based in large part on a design document written by Judy Peachey when Network Server was first implemented.