Abstract

DAB is a very good tool for creating docapps but has some limitations. The only way is to build your jars on a box and update your modules by updating the jars, creating a DocApp and deploying them through the Appinstaller. This article proposes an alternative solution.

The Problem

This article is about installation woes which many people face or have faced when automating build process. During my current stint with a client, we ran in to a very typical problem with deploying modules through Documentum Application Builder (DAB). DAB is a very good tool for creating docapps but we ran into a limitation while deploying modules. The way it is now, you cannot update your modules through an automated build process or by using some other external process. The only way is to build your jars on a box and update your modules by updating the jars, libs by creating a DocApp and deploying them through the Appinstaller. This works if you have an environment which is not very controlled environment. However, in a highly controlled environment, where your build and deployment originates from a box only accessible to a handful of administrators and/or build personnel, this approach doesn’t work.

The Solution

One approach to tackling the problem is writing your own ANT task. I chose the path of writing a Java application that can be called from an ANT script or a shell script. This lessens the burden of learning an another new technology. I thought it would be fun to learn ANT though and create it as a task.

To solve the problem, we created an xml config file that closely depicts the UI used by DAB to define a module. In case of required modules where you can use an object from a repository, we have added an attribute called docbase_modulename. Set this attribute to the name of an already defined dmc_jar object and set the path attribute for the required_modules to “”. You can find more information about this below or in the schema. Using the approach we defined a schema as follows:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="required_modules">
		<xs:complexType mixed="true">
			<xs:sequence>
				<xs:element ref="required_modules" minOccurs="0"/>
			</xs:sequence>
			<xs:attribute name="path">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value=""/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
			<xs:attribute name="name">
				<xs:simpleType>
					<xs:restriction base="xs:string">
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
			<xs:attribute name="docbase_modulename">
				<xs:simpleType>
					<xs:restriction base="xs:string">
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
	<xs:element name="module_config">
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="module" maxOccurs="unbounded"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<xs:element name="module">
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="interfaces"/>
				<xs:element ref="implementations"/>
				<xs:element ref="required_modules"/>
				<xs:element ref="libraries" minOccurs="0"/>
			</xs:sequence>
			<!-- the type of modules which you can define -->
			<xs:attribute name="type" use="required">
			<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="SBO"/>
						<xs:enumeration value="TBO"/>
						<xs:enumeration value=""/>
					</xs:restriction>
				</xs:simpleType>
				</xs:attribute>
			<xs:attribute name="technology" use="required">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="java"/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
			<xs:attribute name="name" type="xs:string" use="required"/>
			<xs:attribute name="checkinas" use="required">
			<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="same"/>
						<xs:enumeration value="major"/>
						<xs:enumeration value="minor"/>
					</xs:restriction>
				</xs:simpleType>
				</xs:attribute>
		</xs:complexType>
	</xs:element>
	<xs:element name="library">
		<xs:complexType>
			<xs:attribute name="sandbox" type="xs:byte" use="required"/>
			<xs:attribute name="path" type="xs:string" use="required"/>
			<xs:attribute name="name" type="xs:string" use="required"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="libraries">
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="library" maxOccurs="unbounded"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<xs:element name="interfaces">
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="interface_jar"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<xs:element name="interface_jar">
		<xs:complexType>
			<xs:attribute name="path" type="xs:string" use="required"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="implementations">
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="implementation"/>
				<xs:element ref="implementation_jar"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<xs:element name="implementation_jar">
		<xs:complexType>
			<xs:attribute name="path" type="xs:string" use="required"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="implementation">
		<xs:complexType>
			<xs:attribute name="classname" use="required">
				<xs:simpleType>
					<xs:restriction base="xs:string">
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
</xs:schema>

How the code works

The code reads the XML config file and builds an list of config objects. This objects contain information on the modules like the interface jars, implementation jars, required modules to use and much more. The Code then goes defines the modules and loads the interface jars and the implementation jars in the current class path using the class loader and creates an instance of the class implementing the interface. The Code also uses reflection to get the interfaces which are implemented by the interface class. This was done because the UI also did that and also the dm_module objects needs the list of interfaces which are set on the object.

Let's take a look at each element of the XML File.

• module_config – is the root of the xml document.
• module element has 4 attributes which contain the following information:
• name – name of the module be created or updated
• type – SBO/TBO. Empty if not either of those
• checkinas – describes the version number to go to in case of an update
• technology – technology being used by module right now its java

A syntax example could look like:

<module name="Test" type= "" checkinas="same" technology  ="java">

All the interfaces required by the modules are defined element interfaces. This element has one of more elements of interface_jar. The interface_jar has the following attributes:

• path – local path to the jar which holds the interfaces

The implementation jars are defined in the implementations element. The implementation element has a attribute called classname which contains the class which implements the interface. In addition to that,this element has one or more implementation_jar elements which has the following attributes:

• path – path of the jar file which houses the implementation of the interfaces.

All the required modules for the module are defined under the required_module element. This element contains one or more of the required_modules elements. This element has the following attributes:

• name – name to assign to the module
• path – local file path to the required module jar. If the path is empty. Use the jar name defined in the docbase_modulename attribute.
• docbase_modulename – this is the name of the dmc_jar which already is in docbase and is used only when the path attribute is empty.

All the required libraries for the modules are defined in the libraries element. This element has zero or more than zero library elements. This element has the following attributes:

• name – name of the dmc_java_library folder to use
• path – local file path to the jar
• sandbox – 1 means Yes 0 means no

A Sample File for this schema would like this

<?xml version="1.0" encoding="UTF-8"?>
<module_config>
	<module name="Test" type= "SBO" checkinas="same" technology  ="java">
		<interfaces>
		<interface_jar path="C:\Samples\int_bof.jar"></interface_jar>
		</interfaces>
		<implementations>
		<implementation classname = " com.mycompany.interface1"/>
		<implementation_jar path ="C:\Samples\imp_bof.jar"/>
		</implementations>
		<required_modules>
		<required_modules name = "test" path =" C:\Samples\hibernate.jar"/>
		</required_modules>
		<libraries>
			<library name = "libtest" path = "C:\Samples\mylib1.jar" sandbox ="1"></library>
			<library name = "libtest1" path = " C:\Samples\mylib2.jar " sandbox ="0"></library>
		</libraries>
	</module>
	</module>
</module_config>

You can run this utility as follows

java  com.mycompany.CreateModules -f<XMLFileName>l -u<UserName> -p<PassWord> -d<DocBase>

Points to Note

• Make sure that this jar file is in your class path
• Make sure that the schema is also part of the jar file
• This Code will run only on JRE 1.5

Extensions

I wasn’t able to figure out how to install Web services using the above approach. I will be working on it and see if I can find a way to extend the code to include deploying Web services also. Some of the attributes for a module like the Min DFC version and JVM version have not been set and also some of non-important attributes like contact and description have not been set. In case you feel that you need this please feel free to modify the code and the XML schema. This code was implemented using the JRE 1.5. If you want this code to work under 1.4, you will have to remove generics and define the collections which are complaint to 1.4.

Download

The code can be downloaded here:

Deploy Modules Utility

References

• Content Server Object Reference
• Documentum App Builder Help Guide
• DFC Development Guide 5.3 Sp4
• Java 2 API docs

About the Author

Harjit Singh has over 10 years experience as a software engineer, and has been assisting customers with technical and business solutions based on Documentum for over 3 years. His expertise includes Java, C++, J2EE,WDK,MTS,DFC,Server Methods and Web Services.Harjit currently works as an independent consultant, focusing on ECM solutions. His clients have included some of the leading names in finance, health and publishing. Harjit Singh has also contributed an extension to the Repository Interrogation Utility on EDN. He can be reached at har_jit@yahoo.com.

Discuss