| Chapter 7 Build, Webapp and Deployment | ||
|---|---|---|
 | 7.3 Application and Plugin Descriptors |  |
| Chapter 7 Build, Webapp and Deployment | ||
|---|---|---|
| | 7.3 Application and Plugin Descriptors | |
XMA-Application's are seperated into components and plug-ins. There may be other modules or layer's within the application, not visible to the client. Any XMA-Application will describe it´s xma-components and plug-in´s within dedicated descriptor files. This descriptors will be used by the xma-runtime basically by the client´s boot runtime. These descriptors are XML-Based.
One central descriptor filexma-app.xml (Application Descriptor) describes the core application, its required files, components and interface versions.
Additionally descriptor files for plugins may exist. They are called plugins.xml (Plugin Descriptor) and are optionally available. This can be used to include plugins that are delivered from 3rd parties.
All descriptors are located in the root directory of the XMA-WebApplication (XMA-WAR-File).
Please see application and plugin descriptor for detailed documentation.
The DTD for this description:
<?xml encoding="UTF-8"?> <!ELEMENT xma_application (component* | resource* | plugin-spec* | plugin-impl* | swt-description? )* > <!ELEMENT component (resource* | resourceLink* )* > <!ATTLIST component name CDATA #REQUIRED> <!ATTLIST component implPackage CDATA #REQUIRED> <!ELEMENT resource EMPTY> <!ATTLIST resource href CDATA #REQUIRED> <!ATTLIST resource type (jar|lib) "jar"> <!ATTLIST resource version CDATA #REQUIRED> <!ATTLIST resource locale CDATA #IMPLIED> <!ATTLIST resource shared (true|True|TRUE|false|False|FALSE) "false"> <!ELEMENT resourceLink EMPTY> <!ATTLIST resourceLink href CDATA #REQUIRED> <!ELEMENT plugin-spec (#PCDATA)> <!ATTLIST plugin-spec requires CDATA #REQUIRED> <!ELEMENT plugin-impl (resource* | resourceLink* )* > <!-- a plugin can implement only client or only server or both --> <!ATTLIST plugin-impl implClient CDATA #IMPLIED> <!ATTLIST plugin-impl implServer CDATA #IMPLIED> <!ATTLIST plugin-impl implements CDATA #REQUIRED> <!ELEMENT swt-description (preinstall*,resource*) > <!ELEMENT preinstall EMPTY > <!ATTLIST preinstall version-number CDATA #REQUIRED>
The application descriptor is used by the xma runtime and boot
runtime. It describes the application from a client´s viewpoint.
XMA-Applications are built up by " Components" .
A component may contain one or more XMA-Dialog´s.
The root elements for a xma application are:
shared top level resoure elementes
application components
plugin descriptions
A resource will be described as such:
<resource href="components/dummycomponentclient.jar" type="jar" version="VERSION_HASH_CODE" locale="de_AT" />
The attibutes are:
href : this specifies the location of the
components JAR-File. it has to be relative to the webapplications
root directory. type : currently only jar and lib are
used. (optional default is jar) version : this element
will contain the hash code for this component JAR-File. It will
created and processed fully authomatically. locale :
currently the locale extension is not used. (optional)
shared : share it in a common cache on the client side.
(optional default is false)
If an application needs resources, that are available to any application component. the JAR-File has to be placed as top-level element into the application descriptors main section.
Resources like the XMA Runtime jar (xmartclient.jar) that are
used by many applications, can be shared between applications. If
they are marked with the attribute shared="true" , they
are cached in the directory /shared common for all
applications. Only the first application that uses it needs to
actually download it. All others will find it allready in the client
side cache.
If the href of the resource points to a versioned
jar-file, the client side boot runtime tries a delta download. A
versioned jar-file is a jar-file containing a version number in the
form
name_<major>.<minor>.<bugfix>.jar .
The client side boot runtime searches for the newest version
allready cached and tries to download the delta file between the
found version and the actually needed version. Therefore to
correctly use this feature the application has to pack the delta
files to previous versions additional to the full version of the
resource in its .war-file. If the delta file is not found a full
download is made automatically.
e.g. to use
<resource href="clientrt/xmartclient_1.6.0.jar" type="jar" version="" shared="true" />
your web application contains
clientrt/xmartclient_1.5.0-1.6.0.xdelta.jar clientrt/xmartclient_1.5.1-1.6.0.xdelta.jar clientrt/xmartclient_1.6.0.jarDelta files contain only new class files and binary deltas of changed class files. They are typically much smaller as the full jar-files. The delta files are part of the installation of new versions of all libraries provided by the XMA-Team.
Delta downloads and shared resources are independent of each other, but are most effectively if used together.
Each component is described with one element:
<component name="DummyComponent"implPackage="at.spardat.xma.samplespar.dummy" >
<resource href="components/dummycomponentclient.jar"type="jar" version="VERSION_HASH_CODE" locale="de_AT" />
<resourceLink href="clientrt/xmartclient.jar" />
<resourceLink href="clientrt/epclient.jar" />
</component>component name : The name of a component is
unique with an application. This name is also used for (external)
component identification. implPackage : the java
package that implements this componontent. This is the base package,
not considering client or server files.
A component can be implemented by one or more resource
packages. included as resource elements directly. Such
resources will be loaded lazily on compnent startup. If a component
is never used, these resources will be never loaded.
A component may require shared resources. This is indicated by
using the element: resourceLink .
Since XMA Bootruntime 1.7.0, the code of the bootruntime itself is independent of SWT. Each XMA application my declare which SWT version it wants to use. The optional tag swt-description is used for this declarations.
An application may declare, that it wants to be executed with SWT 3.1.1. This is done the following way:
<swt-description> <preinstall version-number="3.1.1" /> </swt-description>This application will be executed with SWT 3.1.1.
It is possible to give more than one SWT version number. The order of the version numbers is relevant. SWT will try to use the first SWT version. If it is not installed on client side, the next SWT version is tried. If no declared SWT version is found, the default SWT version will be used. For XMA Bootruntime 1.7.0 the default SWT version number is 3.1.1.
<swt-description> <preinstall version-number="3.2.0" /> <preinstall version-number="3.1.1" /> </swt-description>There is even a possibility to use an SWT version which is not allready installed on the client side. You can specifiy the needed files of SWT as resources. These resources are downloaded, cached and used if none of the SWT versions declared with <preinstall> tags are found on client side. You have to package the declared resources into your webapplication. Of course sharing of resources between applications and delta downloads are possbile here, too.
<swt-description> <preinstall version-number="3.1.1" /> <resource href="swt/swt.jar" type="jar" version="" shared="true"/> <resource href="swt/swt-nl.jar" type="jar" version="" shared="true"/> <resource href="swt/swt-awt-win32-3139.dll" type="lib" version="" shared="true"/> <resource href="swt/swt-gdip-win32-3139.dll" type="lib" version="" shared="true"/> <resource href="swt/swt-win32-3139.dll" type="lib" version="" shared="true"/> </swt-description>The rules for the decision, which SWT version to use are as follows:
If no swt-description is given in xma-app.xml the default SWT version is used.
The SWT-versions defined in preinstall tags are tried in the order given. The first one found installed on client side is used.
If no preinstall tag is presend or none of the SWT-versions defined in preinstall tags was found, all the given resources are downloaded and used by the classloader. There is no order defined on the resources. If not all resources could be downloaded successfully, the application fails.
If no resources are defined, the default SWT version is used.
If components of different server side web applications are integrated into one client side application, only the first web application can decide which SWT version to use for the whole client side application. SWT descriptions of the other web applications will be ignored.
<resourceLink href="clientrt/epclient.jar" />
href : this specifies the location of the
required resource file. it has to be relative to the webapplications
root directory.
Resources may be shared among several components. A shared
resource will be defined as top-level element, and referenced by all
dependent components via resourceLink . The resource
link informs the boot runtime about dependencies between components
and shared resouce files. The boot runtime may decide to delay the
download of a resource until it is actually required. A resource
link must be resolved with one actual resource entry.
<plugin-spec requires="at.spardat.xma.security.Authorisation" />
An application must declare its dependencies to required
plugins. This is done with plugin-spec
references.
An application descriptor may also define required plugins within the application descriptor itself. The plugin implementation (XMA Plugins) can also be delivered from 3rd parties by an external plugins.xml descriptor (Plugin Descriptor) .
Plugin Descriptors can only specify plugin-impl
declarations. Although the DTD would allow component definitions, they
are ignored by the runtime if existing.
<plugin-spec requires="at.spardat.xma.security.Authorisation" />
Attributes:
requires: The required interface (version)
for this plugin
An application must declare its dependencies to required
plugins. This is done with plugin-spec references. In
general, an application will declare several dependencies which will
be resolved with a delivered plugin. This simplifies the
substitution between different vendors for different environments,
or even a dummy implementation can be used during
development.
As for the application descriptor, a plugin descriptor may declare shared or specific resources.
A resource will be described as such:
<resource href="components/dummycomponentclient.jar" type="jar" version="VERSION_HASH_CODE" locale="de_AT" />
The attibutes are:
locale: currently the locale extension is not
used.
type: currently only jar files are
used
version: this element will contain the hash
code for this component JAR-File. It will created and processed
fully authomatically.
href: this specifies the location of the
components JAR-File. it has to be relative to the
webapplications root directory.
The implementation of a plugin is declared with
plugin-impl elements:
<plugin-impl implements="at.spardat.xma.datasource.ITabularDataSource"
implClient="at.spardat.xma.datasource.TabularDataSourceClient"
implServer="at.spardat.xma.datasource.TabularDataSourceServer" >
<resourceLink href="clientrt/xmartclient.jar" />
</plugin-impl/>Attributes:
implements: declares the interface that is
implemented by this plugin. This must match the reference from
plugin-spec .
implClient: this declares the implementation
class that implements the interface for on the client side.
(optional)
implServer: this decldare the implementation
class that implements the interface for the server side.
(optional)
As components a plugin implementation tag may use resources and resource links to reference the packages that contains the implmentation. A plugin may be used client or server side only.
| |  | |
| 7.2 XMA Webapplication |  | 7.4 XMA Plugins |
