The JavaCADD server is the Java application which listens for client service requests, spawns the executables for fullfilling the requests, manages local disk space for the service requests, and returns the results to client. One key concern in setting up any such service is security. When you set up the JavaCADD server, you have complete control over what requests it will respond to, what user the server will run as, and how many concurrent requests are allowed. A JavaCADD server has the same priviledges as whatever user starts up the server since it is simply a Java application which listens on a socket for connection requests.
Requirements: The server has been tested with the JavaCADD client under the following OS/Java JDK/Perl combinations:
Perl is required in order to manage the external tasks which are spawned via JavaCADD client requests. Under NT, OpenNT is required because the Perl (and all OpenNT executables) shipped with OpenNT uses the POSIX subsystem of NT. POSIX provides process groups, which is important to the TaskServer for external task management. Use of the TaskServer without OpenNT is possible (i.e. NT + ActiveWare Win32 Perl), but Win32 does support process groups which limits the ability of the TaskManger to kill tasks. NT + ActiveWare Win32 Perl is NOT recommended and the configuration files in this distribution purposefully do not include this OS/Perl combination (feel free to experiment if you want).
Both the java and perl binaries need to be on the search path of the user which executes the task server. If both ActiveWare Perl and OpenNT Perl are installed, ONLY OpenNT Perl should be on the search path of the user which starts the server.
The JavaCADD Server distribution is available as a ZIP file: task_server102.zip .
Unpack the server distribution into a temporary directory for testing purposes. If this is to be the final
home of the server, be aware that temporary directory space for tasks will be allocated underneath this
directory structure.
Once the server is unpacked, the directory structure is as follows:
OpenNT Users: Because of an oddity with the 'CWD::cwd()' function in Perl under
OpenNT, do not place the task_server distribution at the top level of a disk (i.e.,
//C/task_server). Have it at least one directory down, (i.e., //C/somedir/task_server).
The server uses Java Remote Method Invocation (RMI) for communication
with its clients. A service called the rmiregistry allows
remote clients to locate a server object on a server machine. The
rmiregistry service communicates via a port number; the file
task_server/config/taskServer.pl contains a variable
RMI_REGISTRY_PORT that defines what port the RMI service is to
use. Change this value if you are not happy with the default value.
One way to start the registry is to do the following :
A convenience script for starting the registry under Solaris is in task_server/bin;
execute this script via:
For NT systems, you can start the registry as an NT service given the constraints
specified. A simple batch file for starting the registry is found at task_server/bin/startreg.bat.
This file should be edited to reflect the port number you want to use, and the file should be
executed from a COMMAND window via:
To kill the registry, simply kill the processes associated with the rmiregistry service (it will show up
as a java executable).
Before starting the server, you should edit the file task_server/config/task_server.props.template
and uncomment the three lines starting with taskServer.execCmd,taskServer.filechmod,
taskServer.killCmd corresponding to your particular operating system (the comments in this
file indicate what OSs are supported). These commands deal with the OS-specific commands for spawning and
killing external tasks.
To start the server, you must have the java binary on your search path, and the CLASSPATH variable
should NOT be defined. (OpenNT users: Usually, 'java.exe' is on the search path. Copy 'java.exe' to
'java' so that this script can find it). Then do:
The script will report error messages on the following conditions:
The script may ask you to edit the file task_server/config/taskServer.pl and change the TASK_SERVER_HOST
variable if it detects that Java does not return a fully qualified hostname from its internal getHostName()
functions. A fully qualified host name is needed if you want client machines outside of the server's host
domain to access the server.
Evidence of taskServer startup can be found in task_server/taskServerTmp/server.log:
You can check to see if the taskserver is responding to a simple 'ping' requests by doing:
To check if the taskServer is responding to task execution requests, you can execute one of the demo programs:
Before going any further, it is probably a good idea to discuss the
basic interaction between client and server. The function of the
server is to accept task requests from clients, perform some action to
resolve the task request, and then return results to the client. Part
of the task request is to pass a set of parameters to the server.
These parameters are passed within a Java hashtable as key/value
pairs; the communication mechanism is Java RMI. For security purposes,
the server checks the key/value pairs to see if they match the types
defined within a property file stored on the server. If a key/value
pair is unknown or does not match the type defined in the property
file, then the task request is rejected. Each distinct task or
service to be performed by the server requires a property file. By
convention, the property files are stored under
task_server/config/forms ;one of the parameters passed within
the hashtable is a pathname that tells the server which property file
to use.
The task_server/config/forms/README file defines the different
types that are supported by the server.
The property file is divided into property file groups, which each group defining attribute values for the
property. An example property file is shown below
(task_server/config/forms/clientTest/clientTest1.props):
A property group has the format:
.required : the value is either true or false. This attribute
defines whether the property is required or not. The task will not be
executed if the property is required, but not found by
the server in the hashtable passed by the client.
.userName : the value can be any string; this string is used in
any error messages returned by the server concerning this property.
.type : the value specifies the type of the property; the value must be one of the supported types
specified in the file task_server/config/forms/README.
Any other attributes can be added by the user and are simply ignored
by the server. There is a method by which the client can request the
contents of a property file from the server. The server returns the
property file as a hashtable of hashtables. The keys used in the
first-level hashtable are the propertyNames, the keys used in the 2nd
level hashtable are the attribute names. See the java code in
task_server/demos/clientDev/classes/{ClientTest3.java, PropsUtil.java}
for examples on how to retrieve property file contents from the
server. This feature allows the client to 'discover' new
tool features when the client is started. This is how the
JavaCADD client queries the server for the current tool list stored on
the server.
The server expects the hashtable passed to it by the client to contain
a key whose name is propertyName, and whose value is the
string value to be passed to the tool that will execute the task. All values of keys in the
hashtable passed by the client to the server should be java
bytestrings.
There are some properties that are recognized by the server. These are:
action : The value of this property tells the server what type
of action is to be done on behalf of the client. Two documented values
are ExternalAction and echoProperties.
ExternalAction is used when you want the server to execute an
external command such as a script on behalf on the client.
echoProperties is used to return the contents of a specified
property file to the client. If ExternalAction is used, two
additional lines must be in the property file; these lines specify the
pathname of the external command and a string to be used in error
messages concerning the execution of this command. The format of
these lines are shown below:
properties : The value of this property is the pathname of the properties file to be used when
checking the key/value pairs of the hashtable from the client. The pathname is relative to the
config directory of the task server ; an example value would be
forms/clientTest/clientTest1.props.
password : This is an optional property. It can be used to password protect a particular service
(at this time one password is assigned to the entire service, it is not possible to give passwords for
different users of the service). The file task_server/config/forms/passwords contains key/value
pairs that associate passwords with property files. The value of the password property passed by
the client would need to match the password key in the password file, the property file name
would need to match as well. Password protection of a service is optional.
All other properties in a property file are user defined.
As mentioned previously, if the value of the action property is ExternalAction, then
the externalCmd line found in the property file will be executed as the 'task' by the server.
It should be noted that the value of externalCmd is always read from the property file; it
is not read from the hashtable passed by the client. The server creates a temporary directory
called task_server/task_server_tmp/task_dir_NNNN (NNNN is the directory id) for use by the
task. The command line used by the TaskServer to execute the task is:
The task server will pass the key/value pairs from the client hashtable inside a file
named 'request.props'; this
file contains lines of the form:
The 'request.props' file will be in the
task_dir_NNNN directory if the hashtable contains no properties
of the type 'fileField'. If the hashtable contains properties of the
type 'fileField', then the 'requests.props' file will be in a
directory called request. A file will be created in the
request/ directory for each property of type 'fileField'; the filename
will match the propertyname and the file contents will be the value
passed in the hashtable for that property.
To pass information back to the client after the task has been completed, the task script should
create a directory named "/response". Any files in this directory with extension of ".props" will be assumed
to contain key/value pairs which will be placed in the hashtable which is returned by the server to
the client. Any files in the "/response" directory without a ".props" extension will be placed in the
returned hashtable as key/value pairs where the key is the filename, and the value is the file contents.
The temporary directory space is reclaimed by the server upon task completion unless the
task creates a file named 'state' in the task_dir_NNNN/ directory (contents of the 'state'
file are unimportant). The file task_server/config/taskServer.props.template contains
a variable named "dir.maxDirCnt" which controls the maximum number of temporary directories;
if this count is exceeded the server begins reclaiming temporary directories starting with the oldest
directory. The purpose of the 'state' file is to be able to examine temporary directory space usage
during script debugging; it can also be used to pass information between different tasks. See the
example code in task_server/demos/clientDev for more explanation of this feature.
The object returned by the server to the client task is a Java object of class FormResult.
The instance variables of this object are:
See the directory task_server/demos/clientDev for examples on calling the taskServer directly from Java.
The task_server/demos directory contains example perl scripts
and java programs that illustrate use of the server.
There are three java files under task_server/demos/clientDev/classes that demonstrate basic client/server
interaction. Read the task_server/demos/clientDev/README for a complete description of these demos.
The JavaCADD client GUI is one example of an application built around the basic client/server capability
provided by this code distribution. This text assumes that the user is already familiar with the JavaCADD
GUI demos.
If you look inside the the JavaCADD unix script provided with the JavaCADD client distribution, you will
see that it contains:
The hostname/port pair titan.erc.mssate.edu/23573 is the host
and port that our JavaCADD server is running on. If you want the
JavaCADD client to access your server, then you need to change the
hostname/port number to match your server location (or parameterize
the script to pass in a host/port pair via the command line).
If you execute the JavaCADD script with it pointing to your JavaCADD
server, you will find that the initial JavaCADD tool window will
display a tool choice whose description is An example
tool.... . Launching this tool will produce a tool GUI window
which is simliar to the Viewlogic synthesis service used at MSU. Fill
in the tool fields with whatever you desire, the values will be
largely ignored by the tool which is actually executed (the
VHDL file you specify WILL be sent to the server, so don't send a
100MB file) .. The file task_server/demos/tool1_script.pl is
the perl script which will get executed by this tool request. This
script will echo your parameters to the application window screen, and
then return the VHDL file you sent back to the server, where it will
be placed in the whatever results directory you specified. Comments
found in the tool1_script.pl explain how parameter information
is passed to the script by the server, and how the server expects
client results to be passed from the script.
This section discusses some of the internals of the JavaCADD GUI client; it assumes
that the reader is already familiar JavaCADD GUI interface (look
here for details).
At startup, the JavaCADD GUI contacts the server for the contents of the property file
"config/forms/release/metatool.props". The contents of this property file tells the client
which tool services are available on the server. The example file contained in the
JavaCADD server release contains:
The list of tools presented to the user is simply a list of all the '.description' attributes
found with the toolN properties. When the user selects a tool, then clicks on the
Launch Tool button, the client queries the server for that tool's property file
as specified in the '.default' attribute. The properties found in the property file of the tool
determines how the JavaCADD client will build the GUI interface for the tool.
The tool property file for a JavaCADD GUI tool service not only describes what parameters
will be passed to the tool script during execution, but also determines how the JavaCADD GUI
for the tool service will look. A portion of the tool property file
(config/forms/release/sample_tool1.props) for the sample tool
in the JavaCADD server release is listed below:
Property Attributes used by the JavaCADD GUI are:
The JavaCADD GUI requires two properties for supporting redirection of the tool output
to the tool application window. These properties and associated attributes are given below, and should
be in every tool property file used by the JavaCADD GUI:
1. Unpacking the Server Distribution
task_server/bin scripts for starting/stopping the task server
task_server/src Java Source, compiled classes
task_server/config configuration information for the server & services
task_server/taskServerTmp all temporary directory space allocated here
task_server/demos demos/example code for using the server
2. Testing the Server (starting, stopping)
2.1 Starting the Registry Service
% cd task_server/src/classes
% setenv CLASSPATH "./"
% rmiregistry 23573 &
The CLASSPATH must be set such that the registry can find the classes underneath
task_server/src/classes. The port number '23573' must match the port
number specified in the RMI_REGISTRY_PORT
variable in the file task_server/config/taskServer.pl.
% cd task_server/bin
% perl startreg.pl &
C:\ cd task_server\bin
C:\ startreg.bat
2.2 Starting the TaskServer
% cd task_server/bin
% perl startTaskServer.pl &
Prof-x[8] reese% pwd
/home/reese/vela/task_server/taskServerTmp
Prof-x[9] reese% more server.log
*** Started Server Log: Tue Apr 28 14:35:51 CDT 1998
TaskServerRemoteImpl listener bound in registry as:
//Prof-x.ERC.MsState.Edu:23573/TaskServerRemote
Prof-x[10] reese%
% cd task_server/bin/javautil
% java regcheck prof-x 23573 TaskServerRemote
Task server already active and running!
Version 1.0.2 of task server on Prof-x.ERC.MsState.Edu is alive.
The arguments to 'regcheck' are hostname, port number, and listenerName. The port number
and listenerNames must match the variables defined in the task_server/config/taskServer.pl file.
Prof-x[8] reese% cd task_server/demos/clientDev/classes/
/home/reese/vela/task_server/demos/clientDev/classes
Prof-x[5] reese% java ClientTest3 "forms/clientTest/clientTest1.props" prof-x.erc.msstate.edu 23573
Calling the task server to get the contents of: forms/clientTest/clientTest1.props
Task server foreground task returned
response: forms/clientTest/clientTest1.props
responseHash:
cmdUserName: client test 1
clientHost:
required: false
userName: Client Host Name
type: StringField
password:
required: true
userName: password
type: IdentifierField
clientPort:
required: false
userName: Client Port Number
type: IntField
externalCmd: ../../demos/clientDev/clientTest1.pl
action:
required: true
userName: action
type: PathField
properties:
required: true
userName: properties
type: PathField
inputString:
required: false
userName: input string
type: FileField
directory ID: 0
error code: 0
Prof-x[6] reese%
To kill the server, simply kill the process associated with server (will show up as a Java executable).
3. Server and Client Structure
3.1 Example Property File
# The next two property groups specify the required fields that must
# always be present. If "required" is true, it is an error for the
# field to not be present. The "userName" value is a string that
# should be used in error messages referring to the field. The "type"
# field tells what kind of characters should be expected for the
# field.
action.required = true
action.userName = action
action.type = PathField
properties.required = true
properties.userName = properties
properties.type = PathField
# This next field will make the operation password protected. Any
# request that uses this properties file must include a field
# that contains a password matching a string in the "passwords" file
# under the "configs/forms" directory. Note that in the "passwords"
# file, a password is associated with a particular properties file
# (such as this one). Thus, a given entry in the password file does
# not give permission to make any request -- just the request defined
# in the particular properties file with which it is associated.
password.required = true
password.userName = password
password.type = IdentifierField
# This group of properties defines an application specific field for
# this particular request. The type "FileField" basically turns off
# the security checking for this field since all characters are
# allowed.
inputString.required = false
inputString.userName = input string
inputString.type = FileField
clientHost.required = false
clientHost.userName = Client Host Name
clientHost.type = StringField
clientPort.required = false
clientPort.userName = Client Port Number
clientPort.type = IntField
# These extra properties are needed since we are specifying an
# external action in this request. The "externalCmd" property
# specifies the command line to run as the external action. Whatever
# is started by this command line can assume that its current working
# directory is the temporary directory set up by the task
# server. However, it cannot assume anything about its environment
# variables or path. The "cmdUserName" is a string used in error
# messages or status reports that refer to the command.
#externalCmd = /projects/mpl/cddd/web/clientDev/clientTest1.pl
# Use a relative pathname so that task server demo will be portable
# between sites. This assumes that the location of the temporary
# working directory pool (dir.workingPoolDir) defined in
# ROOTDIR/config/taskserver.props.template is not changed.
externalCmd = ../../demos/clientDev/clientTest1.pl
cmdUserName = client test 1
propertyName.attribute1Name = value
propertyName.attribute2Name = value
etc......
The attributes specify the type of the property, whether the property
is required or not, the default value of the property, etc. The
attributes which each property MUST have and which are checked by the
server are:
3.2 Properties recognized by the server
externalCmd = pathname_to_script
cmdUserName = anystring
3.3 Server Execution of an External Command
taskServer.execCmd TmpDir ExternalAction
where the taskServer.execCmd is specifed in the file task_server/config/taskServer.props.template.
For Solaris OS, the default configuration file causes the command to be:
perl root_dir/src/bin/execProcess.pl TmpDir ExternalAction
The 'execProcess.pl' script first calls the 'setpgrp()' function so
that all processes spawned by this script have the same group process
ID, then changes to 'TmpDir' before executing the
ExternalAction command. The 'execProcess.pl' script also
prints out its process ID to STDERR so that the TaskServer reads this
value and use it later for killing the job if necessary. The
'setpgrp()' function is VERY important since it allows all tasks
spawned by this script to belong to the same process group, and thus
all tasks can be killed by killing the process group (the
taskServer.killCmd property in
task_server/config/taskServer.props.template is the command
used to kill the process group).
You can change the property specifed by taskServer.execCmd to be whatever you
wish, but the ProcessID must be written to STDERR for the TaskServer to read.
Another action which should be performed by the 'taskServer.execCmd' executable
is to set up a common environment for all tasks that are to be executed by this TaskServer.
key = value
4. Example Programs
4.1 Client/Server Demos
4.2 JavaCADD Demo
#!/bin/csh -f
setenv CLASSPATH classes
java JavaCADD titan.erc.msstate.edu 23573
5. JavaCADD GUI Client Internals
Titan[74] reese% more metatool.props
version.description = 1.1
weblink.description = http://www.erc.msstate.edu/mpl/projects/vela/jcadd.html
maillink.description = mpl-software@erc.msstate.edu
tool1.description = An example tool to illustrate JavaCAD GUI
tool1.default = forms/release/sample_tool1.props
tool1.userName = Sample Tool 1
The version, weblink, and maillink properties are
for information purposes when the 'help' menu is accessed. Tool
properties are named 'toolN'; the default attribute specifies
the property file to be used in accessing this tool service.
5.1 Tool Property Files
compressed_file.required = true
compressed_file.userName = compressed_file
compressed_file.type = FileField
compressed_file.description = VHDL File
compressed_file.level = 15
technology.required = true
technology.userName = technology
technology.type = MultiIdentifierField
technology.choices = Xilinx xc4000|Altera MAX|Actel act1|Actel act2|Actel act3
technology.choicedelimiters = |
technology.description = Target Technology
technology.level = 14
designName.required = true
designName.userName = designName
designName.type = IdentifierField
designName.description = Design Name
designName.level = 13
compressed_ini.required = false
compressed_ini.userName = compressed_ini
compressed_ini.type = FileField
compressed_ini.description = Optional synth.ini
compressed_ini.level = 12
policy.required = true
policy.userName = policy
policy.type = IdentifierField
policy.choices = area speed
policy.default = area
policy.description = Optimize for
policy.level = 11
optimize.required = true
optimize.userName = optimize
optimize.type = IdentifierField
optimize.choices = yes no
optimize.default = yes
optimize.description = Perform Optimization
optimize.level = 10
redirectHost.required = false
redirectHost.userName = redirectHost
redirectHost.type = StringField
redirectHost.default = none
redirectPort.required = false
redirectPort.userName = redirectPort
redirectPort.type = IntField
redirectPort.default = 0