|
Versioning Components In Dekoh
Table of Contents
OverviewDekoh uses the J2EE deployment model that facilitates and standardizes the development, deployment, and assembling of your applications. This J2EE model however does not specify solutions for managing aspects such as versioning, upgrades, dependencies between deployed modules, and managing other non-j2ee applications.In the following topics, we will learn about the basics of Version Manager for versioning and upgrading your components. We will also discuss how you can package your components, the different schemas, how to use the features of Version Manager to call components and manage them. The sections in the document are divided into various topics. If you are developing an application that uses components or if you plan to develop your own components, you should be familiar with all the information in the document. If you want to use existing application components available on Dekoh, you may go ahead and read only the last section in the document. What is a ComponentA Component can be defined as any packaged entity (software) which can run on the Dekoh Desktop. A component provides logically complete functionality and can have dependencies on other components. Applications (both J2EE and non-J2EE) are some of the types of components that you can create on Dekoh. You may also package any existing software as a component.Components provide a specific type of service to its users. For example, you may have a component that extracts metadata information from images. So when an application calls your component, it performs the desired operation and returns the extracted metadata information to the application. The component is basically an archive comprising the component.xml file (metadata for instance/version) and user specific content inside. The archive can be a Java archive (using the jar tool in JDK) or a Zip file (packaged using a tool like WinZip™) with all your component specific content (binaries/images/xmls etc.) What does the Version Manager do?The Version Manager helps Dekoh users register their components, provides other users access to these components, and also helps manage the components, by keeping track of the currently available components, their versions, routing requests to the appropriate component URL and so on.Why Version your Components?The components that you build can be based on J2EE specifications (which will typically include dynamic link libraries (DLLs), JAR/WAR files, and runtime environments) or non-J2EE specifications. In both cases, your components will definitely change to address changing requirements.Keeping track of these components, their versions, and their dependencies requires you to understand the development process, and the issues and considerations that you need to keep in mind while creating versions of your components. Dekoh helps you create different versions for all your components, such that it becomes easier to identify, store, track and upgrade them. Advantages of Using the Dekoh Version ManagerEnd Users
Developers
Properties of the Dekoh Versioned ComponentA few important criteria that help organize the Dekoh versioned component:
A Brief Overview of how to Version your ComponentsA well-rounded versioning and deployment strategy considers several overlapping and interdependent concepts. Before you plan your development process, you must keep in mind a few things that help you have a prognostic approach to build your versioned component, and make updates to it.The following diagram illustrates a typical structure for storing your components in your own repository (for example, your website). This approach helps you record details about the source versions making up the component and its dependencies. Note that this is not a mandatory structure, only a recommended one. Eight Step Program for a successful Versioned Component DistributionTo build you components in such a way, we recommend an eight-step program that will guide you successfully deploy your versioned components using Dekoh’s Version Manager.
Understanding the Component MetadataYou can add component metadata tags in your component schema (component.xml) file to define the component, component types, dependency details, version etc. A component schema definition file (component.xsd) defines the simple tag declarations (attributes) that should be used in the component.xml file to define the component elements.component.xsd File and its AttributesYou must save the component.xml file in the root directory of your component. The component.xsd file is described below for your reference: The following table describes the metadata elements, their sub-elements and a description for each - defined in the component.xsd file:
Sample component.xml file<?xml version="1.0" encoding="UTF-8"?>
<component xmlns="http://www.dekoh.com/xmlns/component" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enabled="true" xsi:schemaLocation="http://www.dekoh.com/xmlns/component http://www.dekoh.com/schemas/component.xsd">
<id>http://www.dekoh.com/ns/component/portal</id>
<version>0.4.2.4</version>
<type>application</type>
<display-name>Desktop Portal</display-name>
<description>The portal on your desktop (Dekoh Desktop) where you will find all your Dekoh applications and tools</description>
<dependencies>
<dependency type="required">
<id>http://www.dekoh.com/ns/component/PersonalServer</id>
<maxversion>0.4.2.999</maxversion>
<minversion>0.4.2.2</minversion>
<updateurl>http://www.common.dekoh-dev.com:25000/samples/update?compid=http%3A%2F%2Fwww.dekoh.com%2Fns%2Fcomponent%2FPersonalServer&compversion=</updateurl>
</dependency>
</dependencies>
<callback-classes>
<callback-class>dekoh.portal.install.PortalDBVersionUpdater</callback-class>
</callback-classes>
<updateurl>http://www.common.dekoh-dev.com:25000/samples/update?compid=http%3A%2F%2Fwww.dekoh.com%2Fns%2Fcomponent%2Fportal&compversion=0.4.2.4</updateurl>
<downloadurl>http://www.common.dekoh-dev.com:25000/samples/download?compid=http%3A%2F%2Fwww.dekoh.com%2Fns%2Fcomponent%2Fportal&compversion=0.4.2.4</downloadurl>
<large-icon>themes/app/images/logo32X32.gif</large-icon>
<small-icon>themes/app/images/logo16X16.gif</small-icon>
</component>
Component VersioningDekoh’s version format is: A String consisting of one or more Version parts, separated by dots. For example, 2.1.4.Each version part is itself parsed as a sequence of four parts: <number-a><String-b><number-c><String-d> Each part is optional. Numbers are integers with the base 10, Strings are ASCII. Strings in version parts do not have any special meaning. For Example: 0 (as in 1.0): <number-a>=0 5a (as in 1.5a): <number-a>=5, <string-b>=a 5b4 (as in 3.5b4): <number-a>=5, <string-b>=b, <number-c>=4 * (as in 1.0.*): <string-b>=* Comparing VersionsWhile comparing two version Strings, you must compare the version parts from the left to right. An empty or missing version part is considered as zero.For example: The versions - 1, 1.0, 1.0., 1.0.0, and 1.0... are all equal in Dekoh. This is because the missing version parts are treated as 0 (zero). When a version part of one version String is greater than the corresponding version part of another version string, the first version String is greater than the other one. Else, the version Strings are equal. For example: 1 equals 1. 1. equals 1.0 1.0 equals 1.0.0 1.1 equals 1.1.0 1.1.0 equals 1.1.00 1a.1.0 equals 1a.1.00 1.0.0 is less than 1.1a 1.1a is less than 1.1aa 1.1aa is less than 1.1ab 1.1ab is less than 1.1b 1.1b is less than 1.1c 1.1c is less than 1.1f 1.1.00 is less than 1.10 1.10 is less than 1.* 1.* is less than 1.*.1 1.*.1 is less than 2.0 1. is less than 2. 1.0.2 is less than 1.0.2.3 1.1aa is greater than 1.1a 1.3ab3.5b6ba.6.90.900 is greater than 1.2.4.4a.b.v.b.h.j.56.565656.9000b.bh7 Managing Multiple Version Information using the versions.xml FileThe information for all your available component versions is managed in the versions.xml file. A version schema definition file (versions.xsd) defines the simple tag declarations (attributes) that should be used in the versions.xml file to define the component elements. The file can comprise of only a list of updatable versions or all available versions, where each version is represented by a URL and points to a component.xml file.The Server hosting the component usually maintains this file. If you host your application on Dekoh, then Dekoh automatically generates the versions.xml file and updates it regularly. In case you host your component application on a third party server (for example, your own website), you must create and update the versions.xml file as and when required. The versions.xsd file is described below for your reference: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema xmlns:versions="http://www.dekoh.com/xmlns/versions"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
targetNamespace="http://www.dekoh.com/xmlns/versions">
<xs:element name="available-versions">
<xs:complexType>
<xs:sequence>
<xs:element ref="versions:id"/>
<xs:element ref="versions:available-version" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="version" use="optional">
<xs:simpleType>
<xs:restriction base="xs:string"/>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="available-version" type="xs:string"/>
<xs:element name="id" type="xs:string"/>
</xs:schema>
The following table describes the metadata elements, their sub-elements and a description for each - defined in the versions.xsd file:
Sample: versions.xml file<?xml version="1.0" encoding="UTF-8"?> <available-versions version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dekoh.com/xmlns/versions http://www.dekoh.com/schemas/versions.xsd" xmlns="http://www.dekoh.com/xmlns/versions"> <id>http://www.dekoh.com/ns/component/app/PhotoShare</id> <available-version>http://dekoh:25000/samples/component?compid=http://www.dekoh.com/ns/component/app/PhotoShare&compversion=1.0</available-version> </available-versions> URL Query KeysThe Update URL always points to the versions.xml file, which typically lists all the available versions of the component. The Update URL must be specified only when you host your components on a third party website, or when you host only the component.xml file on Dekoh and the component itself on a third party website.You use the Query Keys or Placeholders to fine-tune the response of the Update URL. For example, use query keys if you want to return only the latest version of the component, instead of all available versions. In such a case, you must know the currently installed version on Dekoh Desktop, which can be known only when there is an update request. For Example If you write the updateurl as http://www.mysite.com/update?compid=mycomponentID&compversion=%compversion%, the Dekoh Desktop will automatically replace the %compversion% with the currently installed version, before making the request. And the final query will look like this (assuming the version installed is 1.4.56b) - http://www.mysite.com/update?compid=mycomponentID&compversion=1.4.56b So if there's a server component, say a Servlet, on your website which understands this URL, it can dynamically send a versions.xml file in the response. This will contain the available versions of the component which are above 1.4.56b (if any), and return only those instead of returning all the versions. Callback ClassesYou use callback classes in Dekoh for specific purposes, such as setting your database properties between versions or for gaining more control over the installation and uninstallation processes on Dekoh Desktop. These callback classes are implemented in Java for the specfic events, and for each component. For example, preInstall and postInstall callbacks.Implementing your Callback ClassesYour callback class must implement the interface com.pramati.bfly.vm.api.UpdateHandlerThe interface UpdateHandler contains the following information: public interface UpdateHandler {
void init(Map<String, String> initParams);
void preInstall(InstallEnv env) throws InstallationException;
void postInstall(InstallEnv env) throws InstallationException;
void preUninstall(InstallEnv env) throws InstallationException;
void postUninstall(InstallEnv env) throws InstallationException;
}
Your component can have multiple implementations of callback classes. You must specify the fully qualified callback class name in the component.xml file after implementing the same for your component. Refer the component.xsd file for understanding the schema.
Compiling your Callback ClassesTo compile your callback classes, inlcude the following JAR in your classpath<your Dekoh installation directory>\server\lib\pramati\um.jarAfter you complete implementing your callback classes, you must package the classes in a JAR called callback.jar and place it at the root level of your component archive. Important: Placing the callback.jar anywhere else will lead to your callback class methods not being invoked at all. Typical Usages of Callback Classes
Component DependenciesDependence among components can be defined as the reliance of a component on other(s) to support a specific functionality or configuration. In Dekoh, you define the dependencies amongst different components in the component.xml file. Each component needs a separate component.xml.The attributes that you define for each component your current component depends on are:
Distributing your ComponentThis section describes how to distribute the component. In this section, we discuss how you can
Packaging your Component for DistributionTo distribute your application to other users, you will need to first package your component. In the following section, we explain how to create component downloadable packages, which when hosted on a web server (Dekoh Server or any other third party server) will enable users to download and install the component on their local Dekoh Desktop.To make your application distributable to the end user, you must package the component into a Java archive (using the jar tool in JDK) or a zip file (packaged using a tool like WinZip™) with all your component specific content (binaries/images/xmls etc.) and user specific content within it. Hosting your ComponentYou can host your component once it is ready for distribution, in three ways.
Hosting the component on DekohIf you are hosting your component on Dekoh, upload the packaged archive on Dekoh, and Dekoh users can now view/download/install your component. Note: Ensure that you have created the component.xml (conforming to the schema specified in the component.xsd file), and saved it in the root directory of your application.Hosting only the metadata about the various versions of your application on Dekoh and the Component on a Third Party ServerYou may choose to host your component on a third party server, and place the metadata file on Dekoh. This helps you display information about the component to all Dekoh users while allowing you the freedom to place the component anywhere you please.If you choose to do this, you must specify a link to the versions.xml file, which then points to all the versions of your component that your users can download. Your component.xml and versions.xml should conform to the schemas specified in the component.xsd and versions.xsd files respectively. Hosting both the Component and the metadata about all its versions on a Third Party ServerTo host your component on a third party server, you must upload the component.xml and place it inside your application archive. Your component.xml should conform to the schema specified in the component.xsd file, with all the Update and download URLs (with the query keys). Your component will be served from the third party website like any other normal zip/archive file. You must also create the versions.xml file and ensure that it conforms to the schema specified in the versions.xsd file, to maintain versions for your component. The Update URL in the component.xml file should contain the location of the versions.xml file.Version Management on your Dekoh DesktopThis section gives you information about installing and updating components on your Dekoh Desktop. You can install and update components that are hosted either on the Dekoh, or on a third party server. The section also describes how to uninstall a component from the Dekoh Desktop.How Does Dekoh Determine what Component to Update?Whenever a user clicks on the Update button for a component, Dekoh Desktop first checks the Update URL in the component.xml file and gets the response as a versions.xml file. Note: The file need not be named as versions.xml, just an XML that conforms to the versions.xsd.It then checks with the versions.xml file for the extensions (versions) available, and then verifies whether a new version or versions is available as mentioned in the versions.xml file. In case of mismatched versions, it asks you whether to update the component to its latest version. If you click on Download, the Dekoh Desktop updates your component to the latest version using the Download URL in the specific component, and deletes the older version from the Dekoh Desktop. The process automatically resolves all dependency issues, downloading all components that your component depends on, and the upgrades of these dependee components, if required. . All your components are updated when you restart Dekoh Desktop. This is essential, as components that are being currently used cannot be replaced. This process also avoids situations such as applications having opened files, or loaded libraries, which have not being closed properly. This also becomes necessary when updates are being made to the Dekoh Desktop itself. Installing a ComponentComponents can be hosted on either the Dekoh or another website. If you are installing a component from the Dekoh, you can install the component on a single click after viewing the list of components available in the repository.If the component is hosted on a third party server, you must download the component archive into the following location in your Dekoh Desktop directory /<Dekoh_install_dir>/server/downloads. After you finish downloading the component, restart the Dekoh Desktop. Updating a ComponentComponents can be hosted on either the Dekoh or some other website. If you are updating a component from the Dekoh, you can update the component on a single click after viewing the later versions available in the repository. If you choose to update to a later version, you have to restart the Dekoh Desktop after completion of the process.If you are updating a component from a third party server, the component developer should have maintained the versions.xml and the Update URL in the component.xml file properly. You can then update the component by downloading the latest archive on a single click after viewing the later versions available. Uninstalling a ComponentComponents can be hosted on either the Dekoh or some other website. If you are uninstalling a component from the Dekoh, you can delete the component on a single click (using the small cross icon) after carefully reviewing what you want to delete from the repository. This marks the component for uninstalling. Restart Dekoh Desktop. This will uninstall your application.Note: If you have any component that is dependent on other components, uninstall those components before uninstalling your component. You may also mark them (for uninstallation) in the appropriate order, and then restart Dekoh. After marking your application for uninstallation, if you decide not to go ahead with the uninstallation, cancel the uninstallation by navigating to Installed Applications tab. Click “Restore Application” button under the application marked for uninstallation to start the restoration process. Internal Mechanics of Component Installation, Uninstallation and UpdationDekoh Version Manager handles all component installation/uninstallation and updating of these components. To know how components are installed on your Dekoh Desktop, read the relevant section mentioned before. The component is downloaded using the download URL in the component.xml file. The download request made comprises an HTTP request for downloading the component. Any additional accept-encoding headers are also placed in this download request. These headers are then set for notifying the remote server that the DVM supports - Pack200 and jardiff formats.
The header set is as follows accept-encoding : pack200, jardiff If you are downloading the component from a server that supports either of the formats, or both the above formats, the response it sets in the header is: content-encoding : pack200 content-type : application/x-java-archive-diff The server then sets the content-encoding/content-type header fields appropriately, based on the format(s) it supports. The server must not set any header response that it does not support. This is important as the Dekoh Version Manager tries to read and process the response based on the response header fields. For example: DVM > download request > headers set to accept-encoding : pack200Lets say the target Server is “Dekoh”. This gallery reads the header and confirms that the “pack200” is supported by the client. The Dekoh Server then sends a packed archive as the download, receives the appropriate archive and checks the header field content-encoding. It detects pack200 and tried to unpack the archive to get the original archive. Component InstallationYou can install components during Dekoh Desktop startup. This is the time when the Dekoh Version Manager collects the list of components from the downloads directory and installs them in the correct sequence. You may also install the components at runtime, in case you are downloading the component from a website (for example, Dekoh).In both the above cases, the Dekoh Version Manager does the following:
|
