GISToolkit Server Setup

Installation:

Windows

1. Download Java 

The GISToolkit Server is a Java program, so you will need a Java interpreter to run it.  It has been built and tested against the j2se 1.4.0 and j2se 1.3.0_2 from  Sun Microsystems.  Other 1.2 compatible JDK releases should work as well. Install the interpreter.
2. Update the batch file to point to your installation
The GISToolkitServer.bat needs to point to the correct JDK, and needs to be updated to include the correct jar files.  My JDK is installed in d:\apps\jdk14, so this is where I find the java interpreter.
If java is installed correctly, it should be in your path and the following line should work well.

java -Xms32m -Xmx600m -cp GISToolkit.jar;JimiProClasses.zip;xerces.jar;db2java.zip;jdbc7.1-1.2.jar gistoolkit.server.mapservice.WebMapService server.xml

If not, then you will have to prepend the java with the fully qualified path such as
d:\apps\jdk14\java -Xms32m -Xmx600m -cp GISToolkit.jar;JimiProClasses.zip;xerces.jar;db2java.zip;jdbc7.1-1.2.jar gistoolkit.server.mapservice.WebMapService server.xml

The file server.xml is the configuration file for the server, and must be present.  A default server.xml file should have been provided with the distribution.

The -Xms parameter is a Sun JDK specific parameter which instructs the virtual machine to startup with 32 meg of memory.  The server typically uses less than 14 meg, so this parameter can be adjusted to your specific needs.  If you are using a different JDK, this parameter will most likely have to be removed or replaced.

The -Xmx parameter is a Sun JDK specific parameter which instructs the virtual machine to never use more than 600 meg of memory.  This may again be adjusted to the requirements of your server, and the availability of ram.  Layers with many shapes and large shape files will require additional ram as the server loads the entire shape file before trimming to just the shapes in view.  If you are using a different JDK, this parameter will most likely have to be removed or replaced.

Since the server can use additional extenders, you must include the classes for the extenders in the class path.  If you know what I am talking about, then you know how to do this.  If you are not using extenders, then the path above is fine.

Jar files that are used for data sources you are not using can be safely removed.

3. Run the GISToolkitServer.bat file to start the service as a stand alone process.
4. Test the installation
Start a web browser and go to the URL

http://localhost:40320/admin

This should show you the administration pages for the server so you can go ahead and begin configuring the server.
Go the the "Setup Instructions" later in this document.
Windows Service:

It is likely that you will want to run the server as a stand alone process before attempting to run it as a service, if so follow the "Windows" instructions above, and then skip to here to perform the necissary installation for the server.

1. Download Java : if you have done this already, then there is no need to do it again, we will use the currently installed vm, go to step 2.

The GISToolkit Server is a Java program, so you will need a Java interpreter to run it.  It has been built and tested against the j2se 1.4.0 and j2se 1.3.0_2 from  Sun Microsystems.  Other 1.2 compatible JDK releases should work as well.  Install the interpreter.
2. Update the batch file to point to your installation
Location of the JVM
The ServiceInstall.bat needs to point to the correct JDK, and needs to be updated to include the correct Parameters. My JDK is installed in d:\apps\jdk14, so this is where I find the java interpreter.  The DLL of the interpreter is necissary.
rem ********************************************************************************
rem location of the jvm.
rem jdk 1.3
rem set jvm_path=d:\apps\jdk13\jre\bin\hotspot\jvm.dll
rem jdk 1.4
set jvm_path=d:\apps\jdk14\jre\bin\server\jvm.dll

Set this variable to the location of the vm on your server.  It will most centainly be in a different location.  If this parameter is not correctly set, then the server will fail to start in the Windows Services panel.

Location of the initialization file.
There is an example installation file sent with the distribution.  It will provide a unconfigured server.  The configuration file location can be relative to the server installation directory (below), or may be an absolute path.  Mine is in the same directory as the rest of the software.  This is probably the case.  If this parameter is set incorrectly, the service will start, but will quit almost immediately.
rem ********************************************************************************
rem location of the initialization file
set initfile=server.xml

The location of the server.
This needs to be set to where the necissary jar files are located.  My GISToolkitServer is located in D:\apps\GISServer .  Again, your installation directory will almost certainly be different.  If this parameter is set incorrectly, the service will start, but will quit almost immediately.
rem ********************************************************************************
rem location of the installation directory.  This must be the fully qualified path.
set GISServer_HOME=d:\apps\gisserver

Required Class Path for the Server.
This should be Just fine the way that it is.  If you are using extenders that require additional classes, then update this to include your classes as well.
3. Run the ServiceInstall.bat file to install the service
This should print a message "GISToolkitService" successfully installed.

Should you wish to uninstall the service run the ServiceRemove.batch file.  

The services window should not be open when the service is removed or it may schedule removal of the service for the next time it is closed instead of immediatly.  Close and reopen the services window to see the changes.
4. Test the installation
Start a web browser and go to the URL

http://localhost:40320/admin

This should show you the administration pages for the server so you can go ahead and begin configuring the server.
Go the the "Setup Instructions" later in this document.

Linux

1. Download Java 

The GISToolkit Server is a Java program, so you will need a Java interpreter to run it.  It has been built and tested against the j2se 1.4.0 and j2se 1.3.0_2 from  Sun Microsystems.  Other 1.2 compatible JDK releases should work as well. Install the interpreter.
2. Update the script file to point to your installation
The GISToolkitServer.sh needs to point to the correct JDK, and needs to be updated to include the correct jar files.  My JDK is installed in /usr/java/j2sdk1.4.0/. so this is where I find the java interpreter.

This is an example of my startup command:
/usr/java/j2sdk1.4.0/bin/java -Xms32m -Xmx600m -cp db2java.zip:jsde81_sdk.jar:JimiProClasses.zip:GISToolkit.jar:xerces.jar gistoolkit.server.mapservice.WebMapService server.xml

The file server.xml is the configuration file for the server, and must be present.  A default server.xml file should have been provided with the distribution.

The -Xms parameter is a Sun JDK specific parameter which instructs the virtual machine to startup with 32 meg of memory.  The server typically uses less than 14 meg, so this parameter can be adjusted to your specific needs.  If you are using a different JDK, this parameter will most likely have to be removed or replaced.

The -Xmx parameter is a Sun JDK specific parameter which instructs the virtual machine to never use more than 600 meg of memory.  This may again be adjusted to the requirements of your server, and the availability of ram.  Layers with many shapes and large shape files will require additional ram as the server loads the entire shape file before trimming to just the shapes in view.  If you are using a different JDK, this parameter will most likely have to be removed or replaced.

Since the server can use additional extenders, you must include the classes for the extenders in the class path.  If you know what I am talking about, then you know how to do this.  If you are not using extenders, then the path above is fine.

Jar files that are used for data sources you are not using can be safely removed.

3. Run the GISToolkitServer.sh file to start the service as a stand alone process.
4. Test the installation
Start a web browser and go to the URL

http://localhost:40320/admin

This should show you the administration pages for the server so you can go ahead and begin configuring the server.
Go the the "Setup Instructions" later in this document.

Setup Instruction :

Once you have the administration pages displaying it is a matter of navigating your way through them to add the necissary layers.  Do not add a service without adding layers to it as this could cause the server to start incorrectly: (This is a big we are trying to fix).

The administration pages can be found at:
http://localhost:40320/admin

Changing the host name (Very Important)

The first thing you should do is to change the servername.  This is the name that this server will send back to the client in subsequent links so that the client can again find the server.  To Change this value, go to the "Options" menu under the large G.  This will bring up a screen with two entry boxes.  The first of which is the Banner Image Filename, and if populated with a correct image file name will replace the image at the top of the screen with perhaps a location specific one.  The Host Name parameter is the parameter of interest at the moment.  This should be populated with the name of the host.  such as www.myhost.com, or just simply myhost.  Click the submit button.  This will change the host name in the running server, but will not save this host name to the initialization file so the server will retain the change when it is restarted.  

To save any changes click on the "Save Config"  link at the top of every page!

Adding a Service to the server.

There can be serveral services on a single server.  These services should be used to group like data sets or datasets that are typically viewed together.  In my installation I only have a single service.

Click on the "Server " link at the top of the page.

This will bring you to the list of available services, and will probably say "No Services found", and add an "Add Services " link.  Clicking on the "Add Services" link will bring you to a screen that will start the process of adding a service.  It will ask you for a short Service Name for the service.  This name is used by computer systems to identify the service.  It should not contain spaces or special characters and can be almost anything.  I use "NewSerivce", "TestService","MyService" or the like.  

The next box is the Service Title box, and this is used to identify the service to users of the services.  It will appear in their list of services, and should be descriptive of the service offered.  This title can contain spaces, and special characters.  There is also a URL which (depending on the client) will allow the user to view a web page with additional information about the service.

Click on the "submit" button to send the data to the server and create a blank service.

Once the service is created, the server will take you back to the available services page.  Your service should be included in the list of available services.  Click on the "Service Name" of your service.  This will take you to the configuration page for your service.  Here you have the opportunity to change the name of your service, the title, or the web link.  After this editable information there should be a "No Layers Found in this service." message, after which there is an "Add Layer" link.

Click on the "Add Layer" link.

The first thing the server needs to know about a new layer is the layer name and title.  Again, these are a short name for computers to use and a long name for people to use.  After which  there is the option to create a data source for use with this server.  Different data sources require different parameters to access the data.  Click the data source you would like to use.

Click on the "submit" button to create configure the data source for the new layer.

Shape File Data Source
The only thing a shape file data source needs to know is the location of the shape file.  Only shape files that are accessable from the server can be used.  If you need to upload shape files from your local computer to the server you should use a file transfer protocol to do that, and then add the path from the server to that file here.

DB2 Spatial Extender
If you have a spatial extender data source, there are quite a lot of parameters that are required.  Most are explained.
The server name is the name of the server where the database resides, it may not (and probably will not) be this computer
The database name is the name of the database (NOT THE INSTANCE).  The server will find the database in whichever instance it resides.  The instance and database must be online.
The Schema Name is the name of the schema, it may be the same as the username (mine is most of the time.)
The username is used by the database to authenticate the user logging in.  This user must have select access on the database.
The password (hidden) is used to validate the username at the database.
The port, is the port that the database is listening on.  This is usally configured with the db2jstrt.exe command on the database server, and the second parameter is the port number.  I use db2jstrt 1510 just because I like that number.  This will start a listener process on that port on the database server, this is the port number you should enter here.  In this case 1510.
Shape Column.  The datasource will look through the resulting data for this column and expect a binary formatted stream of shape data.  This should be the same as the argument to and as clauses. ShapeColumn="Shape" db2gse.st_AsBinary(Shape) Shape  Note that all three must be the same.
SRID is the spatial reference ID of the data in the database.
The query.  This is the actually database query sent to the database, the db2gse.st_AsBinary() function converts the shape data to the correct binary format to be read by the datasource.
Preread, This will cause the datasource to read all the data once, and cache it in memory.  This can be usefull for small datasets (that fit in memory), and that are accessed very often.  Leaving this off will cause this data source to only query the data that is in view (asked for), and draw just that.  The datasource will cache this set so a zoom in will not need a requery, but pans, and zoom outs will.  Redraws (fairly common) do not.
PostGIS Data Source
If you have a PostGIS data source, there are some parameters that are required.  Most are explained.
The server name is the name of the server where the database resides, it may not (and probably will not) be this computer
The database name is the name of the database.
The username is used by the database to authenticate the user logging in.  This user must have select access on the database.
The password (hidden) is used to validate the username at the database.
The port, is the port that the database is listening on.  The default is 5432.
Shape Column.  The datasource will look through the resulting data for this column and expect a text formated stream of shape data.  This should be the same as the argument to and as clauses. ShapeColumn="the_geom" AsText(the_geom) the_geom  Note that all three must be the same.
SRID is the spatial reference ID of the data in the database.
Query.  This is the actually database query sent to the database, the AsText() function converts the shape data to the correct textual format to be read by the datasource.
Preread, This will cause the datasource to read all the data once, and cache it in memory.  This can be usefull for small datasets (that fit in memory), and that are accessed very often.  Leaving this off will cause this data source to only query the data that is in view (asked for), and draw just that.  The datasource will cache this set so a zoom in will not need a requery, but pans, and zoom outs will.  Redraws (fairly common) do not.
Image File Data Source
This allows you to use an image as the data source.  This is fairly common for raster data sources.
Location of the ImageFile Is the path (again on the server) of where the image is.  JPG, GIF, and PNG images are supported.
In order for the server to know where to draw this image, the image must be georeferenced.  The next four parameters are the locations of the four edges in the display coordinate system.
Click on the "submit" button to create configure the data source for the new layer.

This will bring you the the edit service page that will show you the layer that you just added.  This layer will be viewable from 0 to 180, and will have a default style associated with it.  This style will be black lines with a white fill.  At this point you should be able to brows this service and see the data for your layer.  

Go to the url "http://servername:40320/client " to  view your data.

If you can view the data correctly, you may want to select the " Save Config" link at the top of the page to save this configuration to the configuration file.

From this point you may wish to add additional styles, to the layer, or modify the default style which is simply called "Style".