Network Server Implementation
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:
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.
|