![](https://webarchive.library.unt.edu/web/20130220162158im_/http://dmap.nrlssc.navy.mil/dmap/gidb2/images/developer_header.gif)
Creating a server allows you to bring data in the GIDB® Portal system. What we are calling a "server" is really a bridge that
fills the gap between the GIDB® Portal system and whatever data server type you are wanting to bring in to the system. We usually
refer to this bridge as a "driver".
To create a driver, you must implement (using Java) the interface DatabaseInterfaceModule.DatabaseInterfaceMethods
(Download Package Source
Download Package JavaDocs).
The interface has around 30 methods in it that you must implement for your data source. The interface is changed every so
often to allow for new functionality.
The current architecture uses Apache as a web server and Tomcat as a Servlet Engine. This means that all the drivers run within
the Tomcat context. Once you've created your driver, JAR it up along with any support classes that it needs. Place this JAR file
in the <tomcat>/webapps/ROOT/WEB-INF/lib folder. This will allow your driver class to be put on the classpath that Tomcat uses, and
subsequently allow the driver to be instanced by the driver controller. You will also need to place the following files in the
<tomcat>/webapps/Root/WEB-INF/lib folder: DatabaseInterfaceModule.jar,
GIDBServlet.jar, and CommunicationSupport.jar.
DatabaseInterfaceModule.jar contains the driver interface files. GIDBServlet.jar contains the driver management files.
CommunicationSupport.jar contains files for encryption, compression, and stream IO utilities.
You can download a barebones Apache/Tomcat for Windows configuration here. For Apache, you'll need to edit the <apache>/conf/httpd.conf file and
fill in your correct ServerRoot (Apache folder), ServerAdmin (contail email address), ServerName (your hostname), and
DocumentRoot (root directory where the files are served from). You should also correct any occurance of the default directory
(c:/apache) to wherever you install Apache. The last line of the .conf file directs the connector to Tomcat to start up. Edit
the path as necessary (depending on where you put Tomcat). You can then install Apache as a service using
<apache>/bin/apache -k install -n Apache
For Tomcat, you'll need to edit the <tomcat>/bin/installservice.bat to point to wherever your JRE/JDK is located. Note that you
do NOT have to put any of your server JAR files in the classpath of this command. Any JAR file found in
<tomcat>/webapps/Root/WEB-INF/lib is AUTOMATICALLY added to Tomcat's classpath when it starts up. You should also
look at the file <apache>/conf/workers2.properties to make sure the shm path is correct. Then run
<tomcat>/bin/installservice.bat
to install Tomcat as a service.
We have removed the SSL module from Apache. You'll need this if you want to allow your server to do encryption key requests. You can
email us for it, and if you aren't outside the U.S. we'll probably send it to you.
When creating your driver, you may find that you need a "scratch" directory to write temporary files, or to place config files.
To handle this, the driver (when instanced) is passed
a directory path that has been determined to be suitable for this purpose. This parameter is defined in the file
<tomcat>/webapps/ROOT/WEB-INF/web.xml.
In general, you can pass startup parameters to the servlets using the file <tomcat>/webapps/ROOT/WEB-INF/web.xml. For the
GIDB® Portal system, here is an example web.xml that contains the parameters that the Portal servlets need. You
should look over the web.xml that is already included with the ApacheTomcat.zip to get a feel for how the parameters are passed.
Then you should edit the downloadable web.xml so that it has correct parameters for your hostname, WorkingDirectory, etc and then
use that web.xml to run the GIDB® Portal System servlets (copy it over the one found in the ApacheTomcat.zip file after you
have unzipped it).
Every driver is instanced by reading a config file and passing these config parameters to the driver class through its constructor.
Because constructors could vary, the protocol we use is to require a constructor that takes a Hashmap and also an empty constructor.
We use the empty constructor so that we can call getSetupParameterNames() from the DatabaseInterfaceMethods interface.
This method returns all of the names of the parameters that the driver requires for operation. This is needed by
the admin tool to start your server.
Inside the hashmap that we pass to the other constructor, we place
all the key/value pairs that are found in the config file for the driver, "WorkingDirectory" (for scratch space),
and "ConnectionPoolManager" so that you can have a reference to the driver manager (an instance of DatabaseConnectionPool).
The DatabaseConnectionPool reference is useful in case you want to suspend/resume publication of your driver to the portal
(the method names are suspendPublication() and resumePublication()).
An example driver config file contains the following lines:
DatabaseDriverClassName = arcimsinterfacepkg.ArcIMSInterfaceDriver
DatabaseServerName = Tucson, AZ
DatabaseServerDescription = Tucson, AZ and surrounding Area
url = http://www.ci.tucson.az.us
Servlet Path = /ed-servlet/com.esri.esrimap.Esrimap
Classification = UNCLASSIFIED#^
PortalHosts = columbo.nrlssc.navy.mil
The ordering of these lines is not important. However, ALL driver config files must have the parameters named
"DatabaseDriverClassName", "DatabaseServerName", and "DatabaseServerDescription". Optionally they can also have the
parameter "PortalHosts". "DatabaseDriverClassName" is used to let the driver controller know how to load your class.
"DatabaseDriverClassName" and "DatabaseServerName" are used so that the driver controller can give the user of a client some
information about your driver. "PortalHosts" is a comma-delimited list of Portal hosts to register your driver with. All of
the other parameters in the file (such as "url" and "Servlet Path") are specific to that particular driver.
There are two different ways to instance your driver.
You can set it to "auto-start" when Tomcat starts by placing the full path to its config file in the file
<workingdirectory>/autoservers.txt. You can also instance the server manually by using the admin feature in the GIDB® Client. The feature is launched when you right click on a server node in the data tree and select "admin". The admin feature will allow you
to either load driver parameters from a config file, or enter them manually. Once the parameters are set in the admin feature, you
can then use it to tell the GIDB® server to load the driver, and pass it the config parameters that it has received. You can also
use the admin feature to stop drivers that are already instanced. A note about the admin feature is that it uses encryption so that
someone with evil intent can't abuse your server. This means you will have to create an encryption key for it to use and place
it in the folder <workingdirectory>/serverkeys. You'll also need this same key file when using the admin feature.
All files in <WorkingDirectory>/serverkeys are loaded (and periodically reloaded) and are put in place as encryption keys.
The format of an encryption key (.GIDBKEY file) is:
GIDB® Developers
NRL
555-1212
Building 1005
Stennis Space Center
MS
65000
nrl@nrl.nrl
04/04/2002 13:58
Server Administrator
,.jas;oiuwwýÚÿ4#:sssluaoiu)#($@lskdalkss
The first line is the user name.
Line 2 through 8 are contact information
Line 9 is date of key creation.
Line 10 is the server name that the key is valid for (required).
Line 11 is the encryption key itself (minimum of 24 bytes. No, the example is not a real key).
So, in summary:
The important config files are
<apache>/conf/httpd.conf (Apache config file)
<apache>/conf/workers2.properties (Tomcat config file)
<tomcat>/conf/tomcatapache.conf (loads the Apache-Tomcat connector module)
<tomcat>/webapps/ROOT/WEB-INF/web.xml (configures the GIDB® Portal System servlets)
<WorkingDirectory>/autoservers.txt (autoloads specified drivers when Tomcat starts)
The important other files are
<apache>/modules/mod_jk.dll (module which allows apache to talk to tomcat)
<tomcat>/webapps/ROOT/WEB-INF/lib/DatabaseInterfaceModule.jar (contains the driver interface package)
<tomcat>/webapps/ROOT/WEB-INF/lib/CommunicationSupport.jar (contains encryption, compression, stream IO utilities)
<tomcat>/webapps/ROOT/WEB-INF/lib/GIDBServlet.jar (contains core GIDB® Portal System servlets)
<tomcat>/webapps/ROOT/WEB-INF/lib/YourDriver.jar (contains your implementation of the driver interface)
<WorkingDirectory>/serverkeys/administrator.GIDBKEY (to use admin tool)
A file input plugin allows you to bring in data to the GIDB® Client (through the tree selector) from any file type you want to support.
Input plugins can be added to the Client while it is running. The client will also automatically load any plugins that it finds in
the subirectory (sub to where the client JAR file is) named "plugins".
To create a file input plugin, you must implement the interface mil.navy.nrlssc.GIDBClient.FileInputPlugin
(Source). See the comments in the source file for detailed instructions. This interface has a
few methods that you must implement. Your plugin will return a
FileInputPluginReadResult to the client.
Once you've implemented the interface, JAR your plugin class up (along with any support classes it needs).
You will have to add the GIDBClient.jar to your classpath to compile your plugin.
A file output plugin will allow you to export data from the GIDB® Client into any file format that you wish to support. This
function is not yet finished. Details will be provided when available.
A visualization plugin lets you visualize a single layer of vector features (features that are defined by points, lines and polygons
as apposed to being constituted by pixel data) in any way you desire. Visualization plugins can be added to the client while it is
running by bringing up the layer options window. The client will also automatically load any plugins that it finds in the subdirectory (sub to
where the client JAR file is) named "plugins".
To create a visualization plugin, you must implement the interface mil.navy.nrlssc.GIDBClient.visualizationPlugin (Source). See the comments in the source file for detailed instructions. This interface has
a few methods that you must implement. Once you've done this, JAR your plugin class up (along with any support classes it needs).
You will have to add the GIDBClient.jar to your classpath to compile your plugin.
|