CT 4.0 Upgrade Guide: Configuration

This page details the set of changes you will have to make to upgrade an App from CT version 3.11.2 to version 4.0.

web.xml

Previously, the production filters forced the content served to the browser to be UTF-8. For flat file export we had to move this responsibility out of the prod filters. Existing apps should add <mime-mapping> tags to their web.xml as follows.

Mime mappings

<!-- mime mappings -->
<mime-mapping>
    <extension>woff</extension>
    <mime-type>application/x-font-woff</mime-type>
</mime-mapping>
<mime-mapping>
    <extension>js</extension>
    <mime-type>application/javascript;charset=UTF-8</mime-type>
</mime-mapping>
<mime-mapping>
    <extension>css</extension>
    <mime-type>text/css;charset=UTF-8</mime-type>
</mime-mapping>
<mime-mapping>
    <extension>html</extension>
    <mime-type>text/html;charset=UTF-8</mime-type>
</mime-mapping>
<mime-mapping>
    <extension>xml</extension>
    <mime-type>text/xml;charset=UTF-8</mime-type>
</mime-mapping>

bladerunner-dev-servlets have been removed from BRJS. Existing apps will need to be updated to replace the filter and associated filter-mapping in the web.xml. Instead of com.caplin.cutlass.filter.BladerunnerFilters, use this:

<filter>
        <filter-name>BRJSServletFilter</filter-name>
        <filter-class>org.bladerunnerjs.appserver.BRJSServletFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>BRJSServletFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
    </filter-mapping>

Note that the development version of the filter should only be used in development when running BRJS, and should not be included when you export the app to run in an application server. By wrapping the configuration block with pre-processor comments you can ensure that BRJS will strip out the configuration block when you export the app.

Instead of com.caplin.cutlass.filter.BladerunnerDevFilters, use this:

<!-- start-env:dev -->
<filter>
    <filter-name>BRJSDevServletFilter</filter-name>
    <filter-class>org.bladerunnerjs.appserver.BRJSDevServletFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>BRJSDevServletFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>
<!-- end-env -->

You will also need the following filter, if you are deploying on an https accesible host:

<filter>
    <filter-name>HTTPS</filter-name>
    <filter-class>com.caplin.trader.filter.HttpsRedirect</filter-class>
</filter>
<filter-mapping>
    <filter-name>HTTPS</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Make sure you remove any references to com.caplin.cutlass.filter.BladerunnerProdFilters.

Servlets

Remove any references to com.caplin.cutlass.servlet.BundlerServlet and com.caplin.keymaster.servlet.KeyMasterXHRFrame.

You will need to add the following:

<!-- start-env:dev -->
<servlet>
    <servlet-name>BRJSDevServlet</servlet-name>
    <servlet-class>org.bladerunnerjs.appserver.BRJSDevServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>BRJSDevServlet</servlet-name>
    <url-pattern>/brjs/*</url-pattern>
</servlet-mapping>
<!-- end-env -->

You may need to update URLs to servlets, e.g. any workbench index.html files that point to keymaster servlets.

jetty-env.xml

BoneCp and Guava have been removed

CT4 has removed it’s dependency on BoneCp so its jar is no longer included with our libraries.

If you were using BoneCpDataSource in you web.xml you will need to replace it. The following is a suggested alternative:

<New class="org.eclipse.jetty.plus.jndi.Resource">
        <!-- relative to this webapp's root directory -->
        <Arg><Ref id='webAppCtx'/></Arg>
        <Arg>jdbc/webcentricdb</Arg>
        <Arg>
            <Call class="org.h2.jdbcx.JdbcConnectionPool" name="create">
                <Arg>jdbc:h2:../generated/app/fxtrader/webcentric-db/fxtrader;IFEXISTS=TRUE;AUTO_SERVER=TRUE</Arg>
                <Arg>sa</Arg>
                <Arg type="String"></Arg>
            </Call>
        </Arg>
    </New>

webcentric-db folder has been moved

Previously, webcentric-db folder was generated parallel to apps and sdk folder. Now it is created inside generated/app/<appName>/webcentric-db/<appName>.h2.db.

Replace this configuration:

jdbc:h2:../webcentric-db/fxtrader/fxtrader;IFEXISTS=TRUE;AUTO_SERVER=TRUE

with this:

jdbc:h2:../generated/app/fxtrader/webcentric-db/fxtrader;IFEXISTS=TRUE;AUTO_SERVER=TRUE
To avoid the login page adding a jsessionid URL parameter, add the following:

<arg>org.eclipse.jetty.servlet.SessionIdPathParameterName</arg> <arg>none</arg>

Bundling

Previously, all code had to conform to the namespaced prototype Caplin style. Now, in order to inform BRJS that you are using the legacy style, you must have a .js-style file inside your <appName> folder with the contents:

namespaced-js

This only has to be done once per app. If the .js-style file is not provided, then common-js is assumed. To be explicit, you can specify:

common-js

XML files with non-XML content (e.g. a dummy.xml with a JavaScript style comment) are no longer allowed.

XML comments are now stripped. So if you want to get the bundler to bundle something, instead of putting the class name in a comment, add a dummy attribute to an XML element e.g.

<compositeComponentDefinitions xmlns=" needs="caplin.bootstrap.bootstrap,caplin.component.composite.CompositeComponent">

In index.html files, the <@i18n.bundle@/> tag is now required to appear before the <@js.bundle@/> tag.

Within the workbench folders, the themes folder containing any CSS must now be at the same level as the resources folder, not inside it.

Thirdparty libraries

library.manifest files are now called thirdparty-lib.manifest, and are no longer optional in third-party libraries. They must be located in the root of any third-party library (sdk/libs/javascript/* or apps/<appName>/libs/*) and must have some content (even if it’s just 'js:'). It’s also required to have the following line in each manifest file:

exports: null

If the library is a commonjs style library, then the following line must be included:

commonjsDefinition: true

The manifest files have the following format:

  • js: <comma separated list of js files that make up this lib, if empty include all js files>

  • css: <comma separated list of css files that make up this lib, if empty include all css files>

  • depends: <comma separated list of other thirdparty lib dependencies >

  • exports: the name of the global variable this library defines, this will then be used to automatically add a define block so the library can be 'required'.

Previously, all CSS for third parties were bundled in common.css, regardless of whether the library was included or not.

Now, BRJS will only bundle CSS for third-party libs you include. If you do not include explicit CSS file config inside your manifest, BRJS will bundle all your CSS files. You can however, choose to include specific CSS files only as follows:

css: myCssFile1.css, myCssFile2.css

BRJS no longer bundles resources (CSS, …​) from third-party libs that aren’t used. This may cause problems if you are relying on the CSS reset that is present in a JS lib and you are otherwise not using that library.

Testing

Previously, the src-test folder could be used to auto-bundle test utility classes without having to specify them inside the 'load:' section in jsTestDriver.conf. Also, the src-test folder could live anywhere inside the library/tests folder.

Now, the src-test folder must either:

  • sit parallel to the src folder or

  • be located inside the test-unit/test-acceptance.

Libraries with tests will have to move these src-test folders around accordingly.

com.caplin.jstestdriver.plugin.CutlassBundleInjectorPlugin is now obsolete, this functionality is now handled by BRJS automatically. So any 'plugin:' sections in jsTestDriver.conf files should be removed.

All tests folder must be named "tests", not "test".

Remove this line from jsTestDriver.conf:

- ../../../../../../../../sdk/libs/javascript/thirdparty/caplin-bootstrap/bootstrap-legacy-init.js

bladerunner.conf is now called brjs.conf

CT4 BR BladeRunnerJS Comments

appNamespace

requirePrefix

'appNamespace' renamed to 'requirePrefix' in 'app.conf' file.

defaultInputEncoding

defaultFileCharacterEncoding

'defaultInputEncoding' renamed to 'defaultFileCharacterEncoding' in 'brjs.conf' file

defaultOutputEncoding

REMOVED

This token should be removed from brjs.conf, all content is encoded as utf-8

Themes and Styling

If you have a blade with theme X, and you want to use that theme in the application, then your aspect must now also contain a theme X (it can be just an empty folder) even if you don’t have any aspect level styles for that theme.

Remove any preceding slashes in CSS URL’s, e.g.

url('/images/icon.gif')

should be

url('images/icon.gif')

JARs

Any app-dependant jars should now be placed in the app’s WEB-INF/lib folder. They should no longer be put in conf/java.

See also: