The unit of deployment in Openwings is an installable jar file.
The goal is to have a single jar file that can be used to install
your component.
Setting up your environment is very important. The recommended
structure is
- polices – policy xml files – this is the only requirement
- http - files to be served on the web server
- docs – documentation files
- data – data files your component may need
- lib – executable jar files
- bin – executable script files
- src – source code files
- build.xml – your components ANT build file
Before a component is packaged, however, a cross-platform description
of component execution must first be provided. The mechanism for
this is a policy file, InstallableComponentDescriptorPolicy.xml.
In Openwings, the
InstallableComponentDescriptor is an object (class) and the
InstallableComponentDescriptorPolicy.xml file provides attribute
details that eventually gets loaded into the InstallableComponentDescriptor
class during component installation. Occasionally the InstallableComponentDescriptorPolicy
and InstallableComponentDescriptor are terms that are used interchangeably.
The InstallableComponentDescriptorPolicy.xml file can be created
and populated using the policy editor. (Run owediticd.bat or owediticd.csh,
located in the bin directory of openwings). Click
here for descriptions of each attribute in the InstallableComponentDescriptor.
After this xml file is created, it must be placed in the policies
directory of the installable image (i.e., your component's Jar
file).
How To Use the Editor
When you bring up the editor, you will see several buttons in
the top left hand corner.
Click for full size image
The first two buttons allow you to create new policy files. Click
one and you will be prompted for a name. Enter any short text
name and a blank component descriptor (or installable component
descriptor) will be presented.
The next few buttons denote “open”, “save” and “delete” respectively.
The last button (with a magic wand icon) indicates the template
wizard.
The template wizard provides template files, each with a description
to help you choose the best one to work with. There are to InstallableComponentDescriptor
templates and two ComponentDescriptor templates:
|
1
|
Java Executable Template (ICD)
|
|
2
|
Java Non-Executable Template (ICD)
|
3 |
Java Executable Template (CD)
|
4 |
Java Non-Executable Template (CD)
|
Simply select one. The resulting template will show what attributes
need to be filled in. For example there might be the comment <enter
component name here> in the component name attribute
to indicate this field needs information.
Alternatively, you can open a policy descriptor belonging to
one component, modify it and save it as the component descriptor
for another component.
Regardless which path you choose, there are a couple of important
things to be aware of.
IMPORTANT: The
UniqueID attribute (the first field) in the InstallableComponentDescriptor
must be unique. Use the "new" button next to this field
to make sure it’s different. You need to remember to do this should
the InstallableComponentDescriptor you are presently creating
was originally copied from somewhere else. If you use the Wizard,
the Wizard will ensure uniqueness.
Also, if your component has a version number, be aware that Install
Service of Openwings will concatenate the component name with
a dash and the version when the root directory for your component
is created during component installation. Consider the Launcher
demo as an example. The
Component Name attribute in the InstallableComponentDescriptor
is "Launcher_im" and the Version
attribute in the InstallableComponentDescriptor is "1.0".
When the Launcher demo becomes installed, Openwings will use these
two attributes to make the root directory for the component ("Launcher_im-1.0"
in this case). You can therefore use version numbers to help you
create variations of any component you may wish to design.
Example
Consider some of the attributes in the
InstallableComponentDescriptor for the HelloWorld demo; specifically,
HelloWorldProvider and HelloWorldServiceSync.
Most of the attributes are self-descriptive and won’t be mentioned
here since we have provided clear definitions for them here.
Note: Attributes in the InstallableComponentDescriptor
are case sensitive!
What may not be clear is how to populate the
Resolvable Codebase and
Resolvable Classpath string array attributes. In short, if
a component is a recipient or a provider of mobile code, then
the codebase array must be used. The classpath array is used for
any local classes that might be needed.
In both cases these array attributes are required by Container
Services so that it can know how to execute components. Install
Service of Openwings resolves the Resolvable Codebase and Resolvable
Classpath arrays into the Codebase and Classpath URL array attributes
of the InstallableComponentDescriptor.
Details regarding component resolution has already been discussed
in the Dependency Resolution
and Dependency
Substitution sections. It’s important that these are thoroughly
understood.
For now, however, let’s take a look at how codebase and classpath
arrays can be used by examining the HelloWorld demo.
We’ll start with the synchronous example. Recall
HelloWorldUser becomes a listener of
HelloWorldProvider using the
HelloWorldServiceSynchronous class and waits until the call
returns before continuing. The codebase in the HelloWorldServiceSync
component must therefore contain the file URL of the compiled
interface because it’s through the interface the service is provided.
So the codebase URL array in component HelloWorldServiceSync
contains
http://PC-SAMPLE02:8880//install/lib/HelloWorldServiceSync_if.jar
Now HelloWorldProvider implements the HelloWorldServiceSynchronous
interface. Remember also that the service object gets distributed;
that Container Services actually wraps the object in a connector.
That is why the HelloWorldProvider is the component that generates
the synchronous connector. (see its build.xml file) Since this
service is providing the mobile code, the following file URL’s
are listed in it’s codebase:
Codebase In HelloWorldProvider:
http://PC-SAMPLE02:8880//install/HelloWorldProvider_im-0.1/HelloWorldServiceSynchronousRMI_cns.jar
http://PC-SAMPLE02:8880//install/lib/HelloWorldServiceSync_if.jar
http://PC-SAMPLE02:8880/gd_openwings_dl.jar
The first URL is the component interface. The second URL
is the RMI connector containing the
classes supporting the distributed service object. Note: this
entry was word-wrapped to the next line. You might see that
occasionally in this tutorial. The last URL is for Openwings.
Conversely, the classpath array is used for classes this component
component needs in it’s local classpath. Observe the classpath
array for HelloWorldProvider:
file:/x:/cots2/HelloWorldProvider_im-0.1/lib/HelloWorldProvider.jar
file:/x:/cots2/HelloWorldProvider_im-0.1/lib/HelloWorldServiceSynchronousRMI_cns.jar
file:/x:/cots2/HelloWorldServiceSync_im-0.1/lib/HelloWorldServiceSync_if.jar
file:/x:/cots2/openwings-1.0/lib/gd_openwings.jar
The first three URL's denotes where in Openwings supporting HelloWorld
components have been installed. (The second and third entries were word-wrapped).
Notice it needs executable
files for the synchronous connector as well as the executable
jar file for itself. The last URL is for Openwings.
Likewise, the HelloWorldServiceSync component has just one entry
in it’s classpath. It’s the URL that refers to itself (word-wrapped).
file:/x:/cots2/HelloWorldServiceSync_im-0.1/lib/HelloWorldServiceSync_if.jar
The above discussion is an example of codebase and classpath
after Dependency Substitution
and Dependency Resolution.
Recall, Install Service populates these URL attributes. A user
specifies component dependencies using the Resolvable Codebase
and Resolvable Classpath string arrays - making use of
Property key/value pairs and the component substitution mechanism.
Debugging Codebase and Classpath entries
By now it should be understood that entries are made in the
Resolvable Codebase and
Resolvable Classpath attributes of the
InstallableComponentDescriptor and Install Service resolves
and substitutes these entries into url arrays of
Codebase and
Classpath. If something is wrong how can one find the error?
We know something is wrong if the component cannot reach a RESOLVED
state.
Install Service provides information when it cannot resolve
something in these attributes. It will create a file under the root
directory of your component. The file name is componentLog.txt
and it will contain helpful information about the
Resolvable Codebase and Resolvable Classpath attributes so that you can change an appropriate entry.
Here is an example:
** CLASSPATH ERROR ** |
${HelloWorldProvider_im.property.net.openwings.install.libDir}\HelloWorldServiceSynchronousRMI_cns.jar |
${HelloWorldProvider_im.property.net.openwings.install.libDir}\HelloWorldProvider.jar |
error ==> ${HelloWorldServiceSync_im.classpath} substitution did not take place or URL type is wrong |
${openwings.property.net.openwings.install.libDir}/gd_openwings.jar |
Notice the third entry has an error (the first two entries were word-wrapped).
Here, Install Service was not able to substitute the
entry simply because the HelloWorldServiceSync_im component had not yet been installed.
That is why substitution could not take place. Simply install the needed
component. The file, componentLog.txt will be deleted and this component
should be able to be resolved.
Install service may not always be able to specify exactly WHY something is not
able to resolve. Sometimes it is a simple typo or spelling error. But it
will tell you where the error occurred so it can be fixed.
Some possible causes of errors to consider are:
- a dependent component is not installed
- a dependent component is installed but is not in a RESOLVED state
- a spelling error exists (or a typo; missing a period or using parenthesis instead of a brace)
- circular dependencies exists
- for codebase, the URL must be a http URL
- for classpath, the URL must be a file URL
The Install State Attribute
Of particular note is the last attribute in the
InstallableComponentDescriptor; the
Install State. Components can have four states:
UNINSTALLED – the initial state
AUTHENTICATED – refers to jar authentication
INSTALLED – component has been installed in Openwings
RESOLVED – a components dependencies have been resolved.
Briefly, RESOLVED refers to a component that might have a dependency
on another component. This was seen in the classpath array for
HelloWorldProvider. HelloWorldProvider depends on the HelloWorldServiceSync
component, otherwise it cannot be executed. Therefore, HelloWorldProvider
will only reach a RESOLVED state when HelloWorldServiceSync is
installed.
Below is a state diagram showing component states:
When the
InstallableComponentDescriptor.xml file has been created
and completed, be sure to place it in the policies directory of
your component.
Finally, once all the directories have been populated for your
component the component is ready to be packaged. To package a
component, use your
build.xml file (in the root of your component directory) and
execute the command “ant image” from the command line. Imaging
a component using ANT does the following:
- creates an image directory
- populates directories in the image directory
- lib
- docs
- http
- policies
- src
- jars the image directory
Voila! You will now have an installable jar file.
Back to Tutorial Trails
