External Configurations and Properties

When deploying to a client environment, it's beneficial to have the OC WAR/AMP be environmentally agnostic. That is, you should be able to deploy the OC WAR/AMP to any environment without making any changes. This is achieved by taking any environment specific properties out of the deployed WAR/AMP and putting them in an external properties file. Note, to learn how to do the same thing with other TSG projects see here.

By default Tomcat's classpath only extends to the WARs in the webapps directory. To pass the shared/classes and shared/jars directories on the classpath, add the following configuration to TOMCAT_HOME/conf/catalina.properties. Depending on tomcat version, you may need to create these folders first at {TOMCAT_HOME}/shared/classes and {TOMCAT_HOME}/shared/lib:

#
# List of comma-separated paths defining the contents of the "shared"
# classloader. Prefixes should be used to define what is the repository type.
# Path may be relative to the CATALINA_BASE path or absolute. If left as blank,
# the "common" loader will be used as Catalina's "shared" loader.
# Examples:
#     "foo": Add this folder as a class repository
#     "foo/*.jar": Add all the JARs of the specified folder as class
#                  repositories
#     "foo/bar.jar": Add bar.jar as a class repository
# Please note that for single jars, e.g. bar.jar, you need the URL form
# starting with file:.
shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar

As of this writing, this is configuraded around line ~76. You'll notice that Alfresco has this configured by default. That's how alfresco-global.properties is loaded onto the classpath. This is useful for configuring Single Sign-On in HPI as well as OpenContent.

Deploying OC as an OpenContent.war

Create this file: shared/classes/opencontent-override-placeholders.properties and add any properties there as you would to project-placeholders.properties. This file wins in terms of precedence when overriding properties.

Create this file: shared/classes/opeannotate-override-placeholders.properties and add any properties there as you would to defaults.properties. This file wins in terms of precedence when overriding properties.

For Documentum specifically, you'll need to create a copy of dfc.properties in the shared folder. Additionally ensure that dfc.properties doesn't exist within the war, or it will override the dfc.properties we put in the shared folder. This is because the DFC references this file directly, and we can't change the classpath override order for the DFC.

Deploying OC as an Alfresco AMP

Create this file: ALFRESCO_HOME/tomcat/shared/classes/alfresco/module/com.tsgrp.opencontent/opencontent-override-placeholders.properties

The directory matters here as we load OpenContent as a submodule of Alfresco and we want to treat the configuration files the same way.

To enable external properties, include opencontent-override-placeholders.properties like below in your PropertyPlaceholderConfigurer bean in your project's module-context.xml.

    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="order" value="1" />
        <property name="locations">
            <list>
                <value>classpath:@propBase@wizard-alfresco-defaults.properties</value>
                <value>classpath:@propBase@universal-defaults.properties</value>
                <value>classpath:@propBase@project-placeholders.properties</value>
                <value>classpath:@propBase@override-placeholders.properties</value>
                <!--  External overrides  -->
                <value>classpath:@externalPropBase@opencontent-override-placeholders.properties</value>
            </list>
        </property>
        <!-- if one of the default files isn't found, don't freak out... keep calm and carry on -->
        <property name="ignoreResourceNotFound" value="true" />
        <!-- Allow other PropertyPlaceholderConfigurer to run as well -->
        <property name="ignoreUnresolvablePlaceholders" value="true" />
    </bean>

Note - The externalPropBase property determines the exact location of the external properties file in the classpath. If external properties aren't being picked up, this is the first thing to double check.

Deploying OC on JBoss Wildfly

To use OC external properties, create a TSG configuration JBoss module. Create this folder structure in the WILDFLY_HOME/modules directory: com/tsgrp/configuration/main

In the main directory, create a module.xml file that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="com.tsgrp.configuration">
    <resources>
        <resource-root path="./"/>
    </resources>
</module>

Note that the name of the module corresponds to the TSG configuration module structure. The resource-root tag path attribute will add any files in the com/tsgrp/configuration/main directory.

Copy a opencontent-override-placeholders.properties file into the com/tsgrp/configuration/main directory.

The OpenContent.war/WEB-INF directory needs to include a jboss-deployment-structure.xml file. This can be placed in a client project's branch in the OPENCONTENT_HOME/war directory. This file should look like this:

<?xml version="1.0" encoding="UTF-8"?> 
<jboss-deployment-structure>
   <deployment>
       <dependencies>
           <module name="com.tsgrp.configuration" />
       </dependencies>
   </deployment>
</jboss-deployment-structure>

Note that the module tag name is set to the same package structure that was created in the wildfly modules directory.

External OpenOverlay configurations

In order to configure OpenOverlay from an external path - just place the following two files in the tomcat/shared/classes folder.

However, if you building this for Alfresco then the oc-overlay-config-override.xml goes under the path /shared/classes and the opencontent-override-overlay-spring-config.xml goes under the path /shared/classes/alfresco/module/com.tsgrp.opencontent.

opencontent-override-overlay-spring-config.xml

<?xml version="1.0" encoding="UTF-8" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

    <!-- OverlayConfig object, created through the XmlConfigFactory -->
    <bean id="overlayConfigBean" class="com.tsgrp.openoverlay.core.XmlConfigFactory" factory-method="createInstance">
        <!-- Spring note - even though these elements are 'constructor-arg' elements, they are really params for the createInstance factory method -->
        <constructor-arg value="oc-overlay-config-override.xml" />
        <constructor-arg value="default" />
    </bean> 
</beans>

Then, create an oc-overlay-config-override.xml which consists of the beans with the actual overlay configurations. You can find detailed instructions about how to create this file here.