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