Package org.apache.derby.impl.drda

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.

See:
          Description

Class Summary
AppRequester AppRequester stores information about the application requester.
CcsidManager  
CharacterEncodings  
ClientThread  
CodePoint  
CodePointNameTable This class has a hashtable of CodePoint values.
ConsistencyToken Class which represents an RDB Package Consistency Token.
Database Database stores information about the current database It is used so that a session may have more than one database
DDMReader The DDMReader is used to read DRDA protocol.
DDMWriter The DDMWriter is used to write DRDA protocol.
DecryptionManager This class is used to decrypt password and/or userid.
DRDAConnThread This class translates DRDA protocol from an application requester to JDBC for Derby and then translates the results from Derby to DRDA for return to the application requester.
DRDAConnThread.PublicBufferOutputStream  
DRDAProtocolExceptionInfo  
DRDAResultSet DRDAResultSet holds result set information
DRDAStatement DRDAStatement stores information about the statement being executed
DRDAStatement.DrdaParamState This class is used to keep track of the statement's parameters as they are received from the client.
DRDAString This class provides functionality for reusing buffers and strings when parsing DRDA packets.
DRDAXAProtocol This class translates DRDA XA protocol from an application requester to XA calls for Derby and then translates the results from Derby to DRDA for return to the application requester.
DRDAXid  
DssConstants This class defines DSS constants that are shared in the classes implementing the DRDA protocol.
DssTrace  
EbcdicCcsidManager A concrete implementation of a CcsidMgr used to convert between Java UCS2 and Ebcdic as needed to handle character DDM Parameters.
EXTDTAInputStream EXTDTAObjectHolder provides Externalized Large Object representation that does not hold locks until the end of the transaction (DERBY-255) It serves as a holder for lob data and is only valid as long as the original result set from which it came is on the same row.
EXTDTAReaderInputStream Implementation of InputStream which get EXTDTA from the DDMReader.
FailingEXTDTAInputStream A stream class that throws an exception on the first read request.
FdocaConstants  
LayerBStreamedEXTDTAReaderInputStream Implementation of InputStream which get EXTDTA from the DDMReader.
memCheck  
NaiveTrustManager This is a naive trust manager we use when we don't want server authentication.
NetworkServerControlImpl NetworkServerControlImpl does all the work for NetworkServerControl
NetworkServerMBeanImpl This is an implementation of the org.apache.derby.mbeans.drda.NetworkServerMBean, providing management and monitoring capabilities related to the Network Server through JMX.
PiggyBackedSessionData Tracks the most recently piggy-backed session attributes, and provides methods to determine if they have been modified and need to be re-sent to the client.
Pkgnamcsn Class representing a PKGNAMCSN object (RDB Package Name, Consistency Token, and Section Number).
ReEncodedInputStream ReEncodedInputStream passes stream from Reader, which is stream of decoded style, to user of this subclass of InputStream, which is stream of encoded style.
ReEncodedInputStream.PublicBufferOutputStream  
Session Session stores information about the current session It is used so that a DRDAConnThread can work on any session.
SignedBinary Converters from signed binary bytes to Java short, int, or long.
SQLTypes  
StandardEXTDTAReaderInputStream Implementation of InputStream which get EXTDTA from the DDMReader.
TestFile This tests protocol errors and protocol not used by JCC The file containing the test is given as an argument
TestProto This class is used to test error conditions in the protocol.
XADatabase This class contains database state specific to XA, specifically the XAResource that will be used for XA commands.
 

Exception Summary
DRDAProtocolException  
DRDASocketTimeoutException Class used to transport that fact that we had a timeout and should *NOT* disconnect the connection.
 

Package org.apache.derby.impl.drda Description

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

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.


Built on Thu 2012-03-29 21:53:33+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.