1. How do I make an existing application run on Dekoh?

To make your existing applications run on Dekoh, all you need is a simple XML file. This XML file (a metadata descriptor) will help Dekoh manage your application, and handle things like versioning, upgrading, etc.

1. Place the XML file in the root directory of your application archive. An example code is given below:

<?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/appcomp.xsd">
<id>http://www.dekoh.com/ns/component/app/PhotoShare</id> 
<version>1.0</version> 
<display-name>PhotoShare</display-name> 
<description>No, you don't have to upload to share anymore. Your friends can see your photo collection right off your desktop with PhotoShare.</description> 
</component>

1. Save the file under <Dekoh_install_dir>/server/downloads directory.
2. Restart Dekoh.

Note: You can also use the command line shell to deploy your applications on Dekoh. This is especially useful in case your apps are exploded directories.

2. How do I help users install my application (along with Dekoh, if not already installed) from my website?

If you have hosted the application on your own website, you must put the link (www.dekoh.com/cas/instapp.jsp?installableparams=< url to component.xml>) on yuor website. Here <url to component.xml> is the encoded URL which points to the component.xml file containing the appropriate component id and version that you want users to install.
For example:

www.dekoh.com/cas/instapp.jsp?installableparams=http://mysite.com/apps/ticker/v20/component.xml

3. How do I make the component ID unique?

A good practice is to use your website name as part of the component ID to make it unique, especially when you’re hosting it on your website.
For example: http://www.mysite.com/apps/tickerapp
We recommend following this convention which is akin to the XML schema namespace convention.
When you host your apps on Dekoh, Dekoh ensures that your ID does not conflict with other applications that have already been registered. This, however does not guarantee global uniqueness.

4. How do I customize the way my application installs on the user’s computer?

The installer API in Dekoh gives you control over the installation and updation process. You must use it in cases such as when you want to test something before installation, or run some script, or want to automatically migrate from one version to another.

To use the Installer API, you must

Implement a listener interface in Java

com.pramati.bfly.vm.api.UpdateHandler

You can also implement the convenience class, if you want to implement only a few methods

com.pramati.bfly.vm.update.UpdateAdapter

These classes are stored under the directory, <Dekoh install dir>/server/lib/pramati/um.jar

• Package the implementation (and any other supporting classes) in a jar/zip file called callback.jar
• Package the callback.jar archive with your application. Ensure that you place the archive at the root level of the archive.
• Mention the name of the callback class or classes (you can have multiple listeners for the same application) in the component.xml as below

<callback-classes>
        <callback-class>com.mysite.install.TickerHandler</callback-class>
    </callback-classes>

The listener class gives you various listener callbacks during pre/post installation and uninstallation. The same methods are also called during upgrading to a new version.
<Javadocs link for Installer API>
<Link to Reference guide for Installer API>

5. How do I inform Dekoh that other dependent software must be installed for my application to run?

This can be done in two ways

1. You can store the dependent software as another Dekoh component and follow the normal procedure for packaging a component. You can then declare this component in the dependency parameter in your application's component.xml file.

<Link to dependency Ref doc>
<How to package a third party software as a component – link in this howto>

1. You may also package the dependent software along with your application and install it using the installer API.

Note: We recommend that you use the first approach, as this ensures that all dependencies are managed by Dekoh and all installations occur smoothly.

6. How do I publish a new version of my app, and make it available to users?

If you have hosted your app on the Dekoh, then Dekoh will take then care of publishing your new version, adding the required RSS notifications etc. (Upcoming feature)
If you have hosted your app on your own website, you need to set up the version metadata files so that users can find the latest version. To do that, you will basically need to host an an xml file (or a web application which can serve the data as an xml) and conforms with the versions.xsd file <link to dekoh.com versions.xsd schema location. Not there yet.>

This file contains information on all the versions of your application, each as a URL. The URLs point to the component.xml files for each version – these will be hosted on your site as well.

For example, if you have an application called Ticker which has 2 versions (1.0 and 1.5) available, you need to host

1. a versions.xml file with the following sampel code

<?xml version="1.0" encoding="UTF-8"?>
<available-versions xmlns="http://www.dekoh.com/xmlns/versions" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0" 
xsi:schemaLocation="http://www.dekoh.com/xmlns/versions 
http://www.dekoh.com/schemas/versions.xsd">
<id>http://www.dekoh.com/ns/component/portal</id>
<available-version>http://www.mysite.com/apps/v1.0/component.xml</available-version>
<available-version>http://www.mysite.com/apps/v1.5/component.xml</available-version>
</available-versions>

1. and a component.xml for version 1.0

<?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.mysite.com/app/TickerApp</id>
    <version>1.0</version>
    <type>application</type>
    <display-name>Ticker</display-name>
    <description/>
<updateurl>http://www.mysite.com/apps/versions.xml</updateurl>
<downloadurl>http://www.mysite.com/apps/v1.0/ticker.war</downloadurl>
</component>

1. and a third file called component.xml for version 1.5

<?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.mysite.com/app/TickerApp</id>
    <version>1.5</version>
    <type>application</type>
    <display-name>Ticker</display-name>
    <description/>
<updateurl>http://www.mysite.com/apps/versions.xml</updateurl>
<downloadurl>http://www.mysite.com/apps/v1.5/ticker.war</downloadurl>
</component>

Note: The component.xml files must be the same as the one you store inside the application archives hosted on your site.

For more information on fine tuning the update/download requests and responses from the user’s Dekoh Desktops, refer to <Query params in ref doc>.
The following diagram illustrates how the metadata XMLs interact:

7. How do I inform my users about the new available version?

Follow the steps given in the previous question. Once you publish your latest version, Dekoh informs users about the update as soon as they are online. Dekoh finds the updates for all installed applications automatically in a periodic manner.

8. How do I make it mandatory for users to upgrade to a new version?

You cannot mandate your users to upgrade to the new version. You can only inform your users about the later version. Note: Users who have upgraded to the latest version cannot rollback to a previous one.

9. How do I migrate my users from one version to another?

To do this, use the Installer API. The Installer API gives you access to the installation as well as the updation process. When Dekoh finds a new version of your application it notifies the user, and if the user subsequently chooses to install the update, Dekoh invokes all callback classes declared in the component.xml of the new version. Note that the methods are called in the same sequence during installation and updation.

• Install
• preInstall
• Install
• postInstall
• Upgrade
• preInstall
• Install
• postInstall

You can use the same callback class for both install and upgrade. To determine whether it is an install or upgrade process which is invoking your class, you can check whether InstallEnv.getOldVersion is null or not. (InstallEnv is an object provided as part of the callback invocation). If null it means this is a first time installation, if not it will return the currently installed version, while installEnv.getNewVersion returns the version currently being upgraded to.
If you’re using the portal framework and need to migrate database schemas, see <db migration link>.

10. How do I package a third party software as a Dekoh component? How do I use it in another application?

When you want to use a third party software package (say a native DB package) to be installed before your application, you must package the component as a "Generic" type in the component.xml file.

Dekoh defines its components to be of the following types:

• Server (the platform itself)
• Applications (The Dekoh Photos application, or any standard web application)
• Tools (Dekoh MyFlickr tool)

Once your application is defined as any of the above, Dekoh understands these types of components and handles them automatically. When you define your component as generic , they are handled using the callback classes in the Installer API.

For example: When you need the MySQL DB for Windows installed, so that you can run your own blogging application on Dekoh.To do this, you must package MySQL as a Dekoh component such that your users have it installed automatically on thier machines while installing your blogging application.

1. Create a component.xml for MySQL. Assign an unique ID and version to it.
2. Package the mysql.exe binary in a jar/zip archive
3. The installation of MySQL on the target Dekoh Desktop has to be done using callback classes. Implement a callback class and in the preInstall method put the code for executing the mysql.exe binary. Dekoh Desktop will automatically call your callback class. The path to the binary will be provided using the InstallEnv <javadoc link> environment properties object. See sample code for this example <link>here</link>
4. Package the callback class inside an archive called callback.jar and place it in the jar/zip archive you created in step (b) at the root level alongwith mysql.exe
5. Mention the name of your callback class in the component.xml
6. Package the component.xml in the jar/zip.
7. Add a dependency in the component.xml of your blogging application to point to the MySQL id you created just now.

The example above discusses how you must package the component. Once completed, you will also need to register/host as per your chosen method of distribution.