Openwings provides a property mechanism that is an extension
of Java properties. Java properties allow string based key
value pairs. The Openwings extensions allow some neat things to
be done with properties:
- Variable References
- Method References
- File Includes
Openwings uses a PropertyInitializer that sets system
properties from a text file. In addition, property
substitution is supported with Openwings Policy files.
Variable References
Any property can be reference any other property as follows:
${<property name>}
Here is an example:
car=ford
mycar=${car}
Method References
You can also fill in properties with method references.
This can eliminate the need for platform specific environment
variables or scripts. The methods referenced can be public
static or public methods that return a string and take no
parameters. Reflection is used to load the class so it must
be on the classpath additionally. Here is the format for a
method reference:
${@<method>}
Here is an example that fills in a property with the current
date:
date=${@java.util.Date.toString}
File Includes
Property files can include other property files. Here is
the syntax for an include:
#!<file>
Here is an example:
#!myproperties.txt
The Openwings Property File
There are several properties in the Openwings property file that
you might want to utilize. The Openwings properties can be found
in:
${OW_HOME}/openwings-${VERSION}/policies/properties.txt
This file can be found here.
New Installer Property Settings
There are new properties settings in the
Properties attribute of the
InstallableComponentDescriptor. These settings change the
way Install Service substitutes variables in the InstallableComponentDescriptor
for your component. Gone are the substitution variables local,
http, httpDir and localDir that existed in
Openwings 0.8. Openwings now offers an easier substitution mechanism
that includes property inheritance.
Inter-component dependencies are represented through variable
notation of the form
${componentName[-version].property.propertyKey}
The "componentName[-version]" part makes it possible to inherit a property
value from another component. For example, consider an entry in componentA
Properties attribute:
net.openwings.install.docDir=${HelloWorldProvider_im.property.net.openwings.install.docsDir}
Here the documentation for componentA can be found in the HelloWorldProvider_im
component docs directory.
This syntax is shown again in this trail in
Dependency Substitution and is an important part toward component
resolution. Component resolution is something that must occur
before a component can be executed. This notion is discussed in
more detail in the next few sections. For now, be aware of the
propertyKey values and their descriptions listed in the table
below.
Where propertyKey =
|
Description
|
net.openwings.install.installJarURL
|
http location of image jar file, only set if component served
|
net.openwings.install.installFromURL
|
http or file location of the original image jar
from which component was installed
|
net.openwings.install.http
|
http location of root of codebase
|
net.openwings.install.httpDir
|
http url where the http directory was installed.
(note that this is not under the component. It is actually a
folder under the web server to which http content was copied.)
|
net.openwings.install.binDir
|
file url of the location of bin directory
|
net.openwings.install.iconURL
|
http location of icon
|
net.openwings.install.dataDir
|
file url of the location of data directory
|
net.openwings.install.docsDir
|
http url where the docs directory was installed.
|
net.openwings.install.sourceDir
|
file url of the location of source directory
|
net.openwings.install.libDir
|
file url of the location of lib directory
|
net.openwings.install.policyDir
|
file URL of the location of policy directory
|
net.openwings.install.local
|
absolute file location of installed component. This is
not a file url.
|
net.openwings.install.localDir
|
file url of the location of installed component
|
net.openwings.install.static
|
boolean representation denoting whether a
component is a static component or not; "true" means
a component is a static component.
|
Debugging Property Entries
It is possible to get an error in an entry in the Properties attribute
during component resolution. Consider the example above where componentA
refers to the docs directory of the HelloWorldProvider_im component. What
if HelloWorldProvider_im is not installed?
When an error occurs, Install Service will create a log file in the
root directory of the component. The file name is componentLog.txt
and it will provide you with the location of the offending entry in the
Properties attribute. For example, componentLog.txt might contain the message:
Property key = net.openwings.install.docsDir has an invalid value = ${HelloWorldProvider_im.property.net.openwings.install.docsDir}
HelloWorldProvider_im simply has to be installed in order to remove the error.
Once a component is resolved, the Properties attribute of the
InstallableComponentDescriptor could look like what is listed below.
Some of the
entries may be word-wrapped in the example. To help you read the example, know
that property keys always start with "net.openwings.install":
net.openwings.install.installFromURL=file:/D:/Openwings/openwings-1.0/demos/componentA.jar
net.openwings.install.http=http://PC_SAMPLE4:8880/install/componentA
net.openwings.install.localDir=file:/D:/Openwings/componentA/
net.openwings.install.libDir=file:/D:/Openwings/componentA/lib/
net.openwings.install.iconURL=null
net.openwings.install.sourceDir=file:/D:/Openwings/componentA/src/
net.openwings.install.binDir=file:/D:/Openwings/componentA/bin
net.openwings.install.dataDir=file:/D:/Openwings/componentA/data
net.openwings.identity.PropertyFile=file:/D:/Openwings/openwings-1.0/policies/properties.txt
net.openwings.install.local=D:\Openwings\componentA\
net.openwings.install.docsDir=http://PC_SAMPLE4:8880/install/HelloWorldProvider_im/docs
net.openwings.install.installJarURL=http://PC_SAMPLE4:8880/install/componentA/componentA.jar
net.openwings.install.httpDir=http://PC_SAMPLE4:8880/install/componentA/http
net.openwings.install.policyDir=file:/D:/Openwings/componentA/policies/
net.openwings.policy.path=file:/D:/Openwings/componentA/policies/
file:/D:/Openwings/openwings-1.0/policies/
Install Service may not be able to tell you WHY something cannot be
resolved but it can tell you where it is having a problem. If Install Service
can resolve the component, it will delete the componentLog.txt file automatically.
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 (missing period/typo; a parenthesis was used instead of a brace)
- the
property key does not exist
The Policy Property
In the previous page, the notion of
policies was introduced. There is a special property key
net.openwings.policy.path that is used to load policies for
your component.
Notice the last entry (the file urls) in the example Properties above. (note: it is word wrapped).
In that example, policies are to be loaded from componentA first and then from Openwings.
That is the recommended approach when setting the policy path; that is put the component's policy
directory first and then the Openwings policy directory. This is recommened because should
there exist policies with the same name as the Openwings core policy (such as
InstallableComponentDescriptorPolicy.xml), the right policy will be found.
The example above is shown after resolution. Before resolution, when the user creates the policy,
the entry looks like what is shown below. Note: there is a single space in between the two entries for policy path but
it is word wrapped so you can't see it:
net.openwings.policy.path=${componentA.property.net.openwings.install.policyDir} ${openwings.property.net.openwings.policy.path}
The PropertyFile property
The property, net.openwings.identity.PropertyFile, helps
the
Openwings core locate the property file (
property.txt). It too should be included in the Properties
attribute. The entry before resolution looks like this.
net.openwings.identity.PropertyFile=${openwings.property.net.openwings.identity.PropertyFile}
Now you have seen examples of resolution; specifically, property resolution. Resolution also occurs
in classpath and codebase as well as a couple of string attributes in the
Installable Component Descriptor. The next few sections discusses this subject more thoroughly.
Next: Dependency
Resolution
