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

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()).

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

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.


How to make a GIDB® Thick Client File Output 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.