Skip to end of metadata
Go to start of metadata

Introduction

LAMS Tools are designed to be installed individually. Some tools come standard with LAMS and others may be supplied by other people. So there needs to be a simple way and consistent way to deploy a tool.

There is a Java utility that does most of the work. The Deployer has been implemented as a standalone Java application that can be run from the command line via a shell script (or similar). To use this tool, you will need to write a series of SQL scripts and package up your jar, war files, the scripts and the tool to make a deployment package.

An understanding of J2EE Applications, LAMS, JBoss, SQL and LAMS Tools are prerequisites understanding the rest of this page.

Deployment

The main class in the Deploy tool is org.lamsfoundation.lams.tool.deploy.Deploy and it is configured via a deploy.properties file. Each task outlined above is implemented separately as org.lamsfoundation.lams.tool.deploy.Task objects. Each Task object has a setter for each piece of data it requires, an execute method to run it, and optionally getter methods to read output from the task. The Deploy class instantiates, configures and executes each Task in order and then retrieves any required output.

The deployment tool does the following:

  1. Create all DB artifacts (the lams_tool, lams_learning_library & lams_learning_activity records, tool tables and their data). Note that the records in the lams_* tables must be set to invalid!
  2. Update the lams application.xml to include a web module for the Tool's web application.
  3. Copy the Tool's war, jar and properties (language) files to the lams enterprise application directory.
  4. Switch the records in the lams_* tables to valid so LAMS will start using them.

The Deploy class requires four SQL scripts to run (the paths of which are set via the deploy.properties file). These are:

  1. A script to insert a record for the tool in the lams_tool table. It is vital that this record be inserted with the valid_flag set to 0 (false) to prevent the Tool being used before it is fully deployed!
  2. A script to insert a record for the tool in the lams_learning_library table. It is vital that this record be inserted with the valid_flag set to 0 (false) to prevent the Tool being used before it is fully deployed!
  3. A script to insert a record in the lams_learning_activity table for the library and tool just created. Note that this will be a ToolActivity type record. Also note that this is a library activity and should therefore have a learning_library_id not a learning_design_id (see below).
  4. A script to create the tool_* tables for this tool and insert any records in required (such as the default content).
  5. (optional) A script to initialise the database version in the patches table for Autopatch

The values for activity title, activity description, activity help_text, tool_display_name and tool description fields are "default" values - the properties file supplied with the tool should define internationalised versions of these fields. But if the properties file is missing or these entries are missing from the file, then LAMS will fallback to using the values from the database.

Scripts 2-4 will require some data (essentially foreign keys) from records created from previous scripts in the sequence. In order to insert this data into the script a token replacement system is used (using the FileTokenReplacer class in the deploy package):

  • The library script (script 2 above) should use ${tool_id} in place of the actual tool id value (which can't be known until the lams_tool record is created).
  • The activity script (script 3 above) should use ${learning_library_id} and ${tool_id} for the learning_library_id and the tool_id respectively.
  • The tool tables script (script 4 above) should use ${tool_id} and ${default_content_id} for the tool_id and the default_content_id.

The deployer will take care of extracting and replacing the right values.

The deployer is kept in a CVS module called lams_tool_deploy.

Package Structure

The deployment package should be in the following structure:

deploy
|- language
|  |- ApplicationResources.properties, ApplicationResources_zh_CN.properties, chinese_zh.txt
|- lib
|  |- commons-collections.jar, commons-configuration-1.1.jar, commons-dbutils-1.0.jar
|  |- commons-io-1.0.jar, commons-lang-2.0.jar, commons-logging.jar, mysql-connector-java-3.1.12-bin.jar
|  |- lams-tool-deploy.jar
|- SQL
|  |- scripts to create the activity, library and tool table rows, along with the tool's own tables.
|- deploy.bat
|- deploy.xml
|- deploy.sh

The only files you need to write are the SQL files and the properties file.

Creating the deployment package

To make it easier to create the deployment package, an ant task has been created to build the deployment xml file, and the package can be built using ant. Please use this task, rather than creating a manual xml file if possible - many of the values that need to go into the xml file are already in your build script (e.g. database username and password) and it is better to define these values once, than in multiple files.

The class for the ant task is: org.lamsfoundation.lams.tool.deploy.CreatePackageTask

To create the package you need to

  • set up the directory structure in a build area
  • copy the library files from lams_build/deploy-tool/lib to the lib directory
  • copy the properties files from conf/language to the language directory
  • copy the deploy.bat, deploy.sh files from lams_build/deploy-tool to the main directory
  • create the deploy.xml file and copy it into the main directory
  • create the SQL scripts and copy them into the SQL directory.

The files that you need have been copied into lams_build for your convenience. To create a deployment package,
you do not need to use deployment tool's package (lams_tool_deploy).

Given below is the ant task definition from the Forum tool, showing how
this can be done using ant.

This is set up for development. To create a production deployment package you should not include the delete tables script (delete_imscr_tables.SQL) and mode should be set to production.

The first target in this code creates the package in the build directory, and the second task
runs the deployment utility. If you just want to create the package, you just need the first
task.

<!-- =================================================================== -->
<!-- Generate the deploy package                                         -->
<!-- =================================================================== -->
<target name="create-deploy-package" depends="_build"
    description="Generate the deployment package.">

    <echo>+------------------------------------------+</echo>
    <echo>| Generate the deployment package.         |</echo>
    <echo>+------------------------------------------+</echo>
    <path id="deploy.lib.classpath">
        <fileset dir="${deploy.tool.dir}">
            <include name="lib/*.jar"/>
        </fileset>
    </path>

    <mkdir dir="${build.deploy}"/>
    <mkdir dir="${build.deploy}/lib"/>
    <mkdir dir="${build.deploy}/sql"/>
    <mkdir dir="${build.deploy}/language"/>

    <copy overwrite="yes" todir="${build.deploy}/sql">
        <fileset dir="${db.scripts}/">
            <include name="create_lams_tool_forum.sql"/>
            <include name="drop_lams_tool_forum.sql"/>
            <include name="activity_insert.sql"/>
            <include name="library_insert.sql"/>
            <include name="tool_insert.sql"/>
            <include name="db_version_insert.sql"/>
        </fileset>
    </copy>

    <copy overwrite="yes" todir="${build.deploy}/">
        <fileset dir="${deploy.tool.dir}">
            <include name="*.*"/>
        </fileset>
    </copy>

    <copy overwrite="yes" todir="${build.deploy}/lib">
        <fileset dir="${deploy.tool.dir}/lib">
            <include name="*.jar"/>
        </fileset>
    </copy>

    <copy overwrite="yes" todir="${build.deploy}/language">
        <fileset dir="${conf.language.dir}">
            <include name="*.properties"/>
            <include name="*.txt"/>
        </fileset>
    </copy>

    <taskdef name="generateDeployProperties"
        classname="org.lamsfoundation.lams.tool.deploy.CreateToolPackageTask">
        <classpath refid="deploy.lib.classpath"/>
    </taskdef>

    <generateDeployProperties depends="compile"
        mode="development"
        outputPath="${build.deploy}"
        dbPassword="${db.password}"
        dbUsername="${db.username}"
        dbDriverUrl="${db.url}"
        dbDriverClass="com.mysql.jdbc.Driver"
        deployFiles="${build.lib}/${product}.war,${build.lib}/${product}.jar"
        toolSignature="${signature}"
        toolTablesScriptPath="${db.scripts}/create_lams_tool_forum.sql"
        toolTablesDeleteScriptPath="${db.scripts}/drop_lams_tool_forum.sql"
        toolActivityInsertScriptPath="${db.scripts}/activity_insert.sql"
        toolLibraryInsertScriptPath="${db.scripts}/library_insert.sql"
        toolInsertScriptPath="${db.scripts}/tool_insert.sql"
        lamsEarPath="${jboss.deploy}"
        toolContext="${toolContext}"
        toolWebUri="${product}.war"
        languageFilesPackage="org.lamsfoundation.lams.tool.forum">

        <!-- language files go as a fileset. -->
        <!-- Not nice but can't work out how to embed them in a tag. -->
        <fileset dir="${build.deploy}/language">
            <include name="**/*.properties"/>
            <include name="**/*.txt"/>
        </fileset>

    </generateDeployProperties>

</target>

Why do we include the txt files (e.g. chinese_zh.txt) in the deployment package? We want to have the .txt files in the eventual dictionary folder (lams-dictionary.jar) as this is the directory that people will look at to start translating. The .txt files are the "original" files for languages that need UTF-8 encoding and hence are the starting point for these languages.

Using the deployment during development

The deployment tool can be called from ant using the java ant task, as well as from a batch file. This allows the deployment to be used during development.

Given below is the ant task definition from the IMS Content Package tool, showing how this can be done using ant.

If the second parameter to org.lamsfoundation.lams.tool.deploy.Deploy is set to true, then the tool related entries in the core tables are deleted and the tool tables are deleted. This is to make it easier in development. If this is ever used in a testing environment, then it should probably be set to false (which is the default value).

<target name="deploy-tool" depends="create-deploy-package"
    description="Build the war, jar and run the deploy tool. Deletes most old tool
    references from db, creates db tables, application.xml in ear, copies war and jar
    file to ear. deploy-tool is only designed to be run in a development environment, or
    on an empty db. Do not run on a production environment.">

    <path id="deploy.classpath">
        <fileset dir="${build.deploy}">
            <include name="lib/*.jar"/>
        </fileset>
    </path>

    <echo>Deploying the Forum tool</echo>

    <java
        classname="org.lamsfoundation.lams.tool.deploy.Deploy"
        classpathref="deploy.classpath"
        fork="true">
            <arg file="${build.deploy}/deploy.xml"/>
            <arg value="True"/> <!-- forcedb -->
    </java>

</target>

Adding your tool to the main build.

If your tool is one of the standard tool's released with LAMS, please add your tool to the master build. This allows the tool to be built and deployed automatically during the main build.

  • Open up the lams_build project.
  • Add your tool to the "deploy-tools" task in the build.xml script.
  • Make sure you have a task "deploy-tool" in your tool's build script. This should build the package
    and deploy the tool as given in the examples above.
  • Ensure that your definition for the generateDeployProperties call in your tool's build script has lamsEarPath="${jboss.deploy}". This is needed to make the tool's jar and war files copy to the
    correct directory - the value of "${jboss.deploy}" in your own build script will be overridden with
    the value from the master build.xml script.

For example:

<target name="deploy-tools">
    <ant antfile="../${tool_imscp_dir}/build.xml" target="deploy-tool"
            inheritAll="false" >
        <property name="jboss.deploy" location="${jboss.deploy}/lams.ear"/>
    </ant>
</target>

When the deploy-tools task is run, your deploy-tool task will be run.

Running the tool

On a production server, we recommend stopping the LAMS server and backing up the database before installing any tool.

This will allow you to reload the backup if anything should go horribly wrong (and we hope it won't!) and will reduce the chances that someone is trying to use the system while a tool is being deployed. The deployment is designed to reduce the chances of people running into problems if people use the system while installing the tool, but we can't guarantee that there won't be errors while JBoss starts the new files. There is also a chance that running the deployment will cause user's sessions to be terminated, forcing them to log in again.

Tool Upgrades

No support is given for upgrading tools. This needs to be analysed and implemented in the future.

24/9/08: Note database schema upgrades can be handled by using Autopatch - see existing tools for how this is done.

Undeployment

Undeployment is not yet implemented. When it is, the following needs to occur:

  1. Set the records in the lams_* tables for this Tool to invalid: note that this also requires that all learning designs using activities that relate to the Tool are also set to invalid.
  2. Modify the LAMS application.xml to remove the module for the Tool's web application.
  3. Remove the Tool's war and jar files from the lams enterprise application directory.
  4. Drop the Tool's tables.

Some of the functionality exists as part of the development use.

Updating the Tool Deployment Utility

More work needs to be done on the deployment tool - to support tool upgrades and undeployment. To make a change to the utility:

  • Check out the lams_tool_deploy package, lams_build and a tool that uses the deployment tasks.
  • Make your changes and test them using junit testcases.
  • Run "assemble-ear" and "deploy-ear" (in the lams_build build script) to deploy the lams ear to JBoss.
  • Run the "build-tool-deploy-utility task" in the lams_build build script. This will build the deployment utility and copy it into the deploy-tool directory in lams_build.
  • Refresh the lams_build project to ensure the new files are recognised by Eclipse.
  • Run the ant tasks in the chosen tool to test the changes. It should pick up the new code from lams_build.

If you change the libraries or the deployment scripts, you will need to copy the new files into the deploy-tool directory in lams_build.

Dealing with tool's default content in the deployment

  • Assuming the tool's default content id information has been pre-configured in the lams_tool table at installation time, each tool should be able to retrieve its own default content id by calling getToolDefaultContentIdBySignature(String toolSignature) method in the core. A typical tool service pojo does:

private ILamsToolService toolService;
long contentId=0;
contentId=toolService.getToolDefaultContentIdBySignature(toolSignature);
return contentId;

  • No labels