Installation Guide

Two Steps – Environment and CaptainCasa itself

JEE/Jakarta Environment, CaptainCasa

CaptainCasa is a JEE/Jakarta-Servlet based framework. Applications require some Java runtime environment and some servlet container into which they are deployed.

As consequence CaptainCasa comes with two types of installation files:

When installing CaptainCasa Enterprise Client the first time then you need to execute both installation steps – one after the other. When later on installing updates of CaptainCasa you do not need to re-install the environment components a second time – you just need to install the CaptainCasa part.

Which environment?

The first – very important! - question: do you want to base your project on “JEE” (“javax.*” packages) or on “Jakarta” (“jakarta.*” packages)? The decision is independent from CaptainCasa – so you are free to select. - For getting to know CaptainCasa you may quickly decide for one direction – but when it comes to serious first projects, you should carefully select! In the default environments provided by CaptainCasa “JEE” projects are based on Tomcat 9, “Jakarta” projects are based on Tomcat 10.

The next decision is: which Java version to use? - When you create own CaptainCasa projects and compile your project classes, then the classes have to run in the Java runtime of the environment. Running classes with Java compiler output version 17 will not run in a Java/Tomcat-environment running on Java 11.

In general we recommend to use the most up to date environment package that is provided. - You may change the Java version any time! You may also bring in your own Java version without any problems.

Windows Installation

If you already have installed CaptainCasa then stop the corresponding Tomcat instances before installation.

Install Environment Components

Execute the setup of the environment components:

During the installation you are prompted for a directory into which CaptainCasa will be installed (default “C:\EnterpriseClientRISC”). When selecting some own directory: do NOT use a directory location within the Windows “Program Files” of “Program Files (x86)” folder.

Install CaptainCasa Enterprise Client itself

Execute the setup of CaptaiNCasa Enterprise Client:

During the installation you are prompted for a directory. Use the same directory that you used for the environment installation. It is automatically proposed by the installation wizard.

Run Enterprise Client RISC - Demo Workplace

The Demo Workplace shows the features of CaptainCasa Enterprise Client CC. It contains a lot of useful information and code snippets how to use components and how to develop concrete scenarios.


Start the Tomcat instance that provides the demo workplace (and that by default will include the web applications that you develop on your own).

Now start the browser showing the demo application:

The page will present a list of links to the demos, select one of them and you will see the corresponding demos.

For best performance: minimize the Tomcat instance (DOS-Box). The log output that is shown for demo purpose takes a quite significant amount of resources.

Problems with Firewall?

“Windows Defender Firewall” (or other firewall software that you might use) may block the Java environment that comes with the CaptainCasa installation to open up network connections.

There are two options:

org.apache.catalina.LifecycleException: Protocol handler initialization failed

        at org.apache.catalina.connector.Connector.initInternal(Connector.java:1051)

        at org.apache.catalina.util.LifecycleBase.init(LifecycleBase.java:136)

        at org.apache.catalina.core.StandardService.initInternal(StandardService.java:556)

        ...

        ...

Caused by: java.net.SocketException: Permission denied: listen

        at java.base/sun.nio.ch.Net.listen(Native Method)

        at java.base/sun.nio.ch.ServerSocketChannelImpl.bind(Unknown Source)

        ...

        ...

 

In the second case start “Windows Defender Firewall”, select option “Add application or feature...” and add the following program to the list of apps / features:

<installdir>/server/jre/bin/java.exe

 

If using other firewall software please open the configuration settings of this software and assign corresponding permissions for the “java.exe” program.

Run Enterprise Client RISC - Toolset

The CaptainCasa Enterprise Client Toolset is the environment for creating dialogs and binding them to your application processing.



Start the Tomcat instance that provides the toolset.

Now start the browser showing the toolset application:

Linux / Mac OS Installation

If you already have installed CaptainCasa then stop the corresponding Tomcat instances before installation.

Install Environment Components

Create a directory in which you want to place the CaptainCasa installation.

Example (assuming the installation directory is “/opt/EnterpriseClientRISC” and assuming the downloaded field is in the “/home/xyz” directory):

cd /opt

mkdir EnterpriseClientRISC

cd EnterpriseClientRISC

tar -xvf /home/xyz/EnterpriseClientRISC_JRE11Tomcat9.tar.gz

 

Of course you can use any other directory – both for placing the CaptainCasa installation and for keeping the download file.

Install CaptainCasa Enterprise Client itself

Execute the setup of CaptainCasa Enterprise Client:

Example (assuming the installation directory is “/opt/EnterpriseClientRISC” and assuming the downloaded field is in the “/home/xyz” directory):

cd /opt/EnterpriseClientRISC

tar -xvf /home/xyz/EnterpriseClientRISC_6_0_20190812.tar.gz

 

Run Enterprise Client RISC - Demo Workplace

Start the Tomcat instance that provides the demo workplace (and that by default will include the web applications that you develop on your own).

cd /opt/EnterpriseClientRISC

./A_startserver.sh

 

Now start the browser and open URL:

http://localhost:50000/demos/indexRISC.html

Run Enterprise Client RISC - Toolset

Start the Tomcat instance that provides the toolset.

cd /opt/EnterpriseClientRISC

./C1_starttoolsserver.sh

 

Now start the browser and open URL:

http://localhost:51000/editor/indexRISC.html

Details on installation

Installed directories and files

Maybe you want to take a look into the installation directory:

<installdirectory>

  /documentation

  /resources

    ...

    /eclipseplugin

  /server

    /jre            <== JRE used for both Tomcats

    /tomcat         <== Tomcat on port 50000

      /webapps

        /demos          < CaptainCasa Demo WebApp

      ...

    /tomcattools    <== Tomcat on part 51000

      /webapps

        /editor         < CaptainCasa toolset WebApp

      ...

  A_startserver.bat

  ...

 

Default Tomcat configuration

The Tomcat instance for running the applications occupies ports in the 5000* area. The default HTTP-port is “50000”.

The Tomcat instance for running the toolset occupies ports in the 5100* area. The default HTTP-port is “51000”.

In general we recommend to keep the ports as defined when testing / developing with CaptainCasa Enterprise Client RISC. In case of conflicts within your environment you may update the ports by updating the file <tomcat>/conf/server.xml.

Using own environment (Java/Tomcat)

Using own Java version

This is very simple:

Using own Tomcat for running your projects during development

You may also use your own Tomcat. You projects will be run and deployed into the Tomcat installation in the “server/tomcat/” directory – this is the one to adapt. - There is no need to adapt the Tomcat running the CaptainCasa toolset.

We recommend the following steps:

<installdirectory>

    ...

    /eclipseplugin

  /server

    ...

    /tomcat            <== Your tomcat – default 8080

       /bin

       /conf

       /lib

       /webapps

       ...

    /tomcat_cc         <== “Old” Tomcat on port 50000

      /webapps

        /demos             < CaptainCasa Demo WebApp

    ...

 

You now need to adapt three files...

Example (Tomcat 10)

 

<Context>

 

    <!-- Default set of monitored resources. If one of these changes, the    -->

    <!-- web application will be reloaded.                                   -->

    <!--

    <WatchedResource>WEB-INF/web.xml</WatchedResource>

    <WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>

    <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

    -->

 

    <!-- Uncomment this to enable session persistence across Tomcat restarts -->

    <!--

    <Manager pathname="SESSIONS.ser" />

    -->

</Context>

 

Example (Tomcat 10):

 

<Server port="50003" shutdown="SHUTDOWN">

    ...

 

    <Connector port="50000" protocol="HTTP/1.1"

               connectionTimeout="20000"

               redirectPort="50001"

               maxParameterCount="1000"

               />

 

Example: security-constraint, login-config, security-role are commented!

 

<web-app ...>

  ...

  ...

 

  <!-- Define a Security Constraint on this Application -->

  <!-- NOTE: None of these roles are present in the default users file -->

  <!--

  <security-constraint>

    <web-resource-collection>

      <web-resource-name>HTML Manager interface (for humans)</web-resource-name>

      <url-pattern>/html/*</url-pattern>

    </web-resource-collection>

    <auth-constraint>

       <role-name>manager-gui</role-name>

    </auth-constraint>

  </security-constraint>

  <security-constraint>

    <web-resource-collection>

      <web-resource-name>Text Manager interface (for scripts)</web-resource-name>

      <url-pattern>/text/*</url-pattern>

    </web-resource-collection>

    <auth-constraint>

       <role-name>manager-script</role-name>

    </auth-constraint>

  </security-constraint>

  <security-constraint>

    <web-resource-collection>

      <web-resource-name>JMX Proxy interface</web-resource-name>

      <url-pattern>/jmxproxy/*</url-pattern>

    </web-resource-collection>

    <auth-constraint>

       <role-name>manager-jmx</role-name>

    </auth-constraint>

  </security-constraint>

  <security-constraint>

    <web-resource-collection>

      <web-resource-name>Status interface</web-resource-name>

      <url-pattern>/status/*</url-pattern>

    </web-resource-collection>

    <auth-constraint>

       <role-name>manager-gui</role-name>

       <role-name>manager-script</role-name>

       <role-name>manager-jmx</role-name>

       <role-name>manager-status</role-name>

    </auth-constraint>

  </security-constraint>

  -->

  

  <!-- Define the Login Configuration for this Application -->

  <!--

  <login-config>

    <auth-method>BASIC</auth-method>

    <realm-name>Tomcat Manager Application</realm-name>

  </login-config>

  -->

 

  <!-- Security roles referenced by this web application -->

  <!--

  <security-role>

    <description>

      The role that is required to access the HTML Manager pages

    </description>

    <role-name>manager-gui</role-name>

  </security-role>

  <security-role>

    <description>

      The role that is required to access the text Manager pages

    </description>

    <role-name>manager-script</role-name>

  </security-role>

  <security-role>

    <description>

      The role that is required to access the HTML JMX Proxy

    </description>

    <role-name>manager-jmx</role-name>

  </security-role>

  <security-role>

    <description>

      The role that is required to access to the Manager Status pages

    </description>

    <role-name>manager-status</role-name>

  </security-role>

  -->

 

  ...

  ...

</web-app>

 

You now exchanged the Tomcat and – after some test run – can remove the “tomcat_cc” directory.

 

Eclipse Plugin

CaptainCasa comes with a little plugin to simplify the development with Eclipse.

What does the plugin do?

The tools of CaptainCasa are operating on the same directory that also used by the corresponding Eclipse project. Whenever a change (e.g. to a layout definition) is done within the CaptainCasa tools, a “signal file” is written into the project folder. The pluging scans this “signal file” and automatically refreshes the project.

Result: changes due to CaptainCasa tools are automatically scanned and lead to an updated of the Eclipse project – you do not have to manually refresh the project against the file system.

Why is there no plugin for NetBeans and IDEA?

...the scanning of the project files is done automatically by both of the tools in a fast way – there is no need for plugin to trigger this.

Installation

The plugin is part of the “/resources” folder, the name is “org.eclnt.eclipseplugin.zip”.

Eclipse <= 4.4 (Luna)

If using Eclipse <= 4.4 (Luna): Unzip the file into your eclipse installation directory.

Eclipse >= 4.5 (Mars)

Copy the .jar file contained in the zip-file into the /dropins-folder of your Eclipse installation directory.

Running the plugin

After coying the file and restarting Eclipse, you need to start the plugin. Then open the menu...



...and select the CaptainCasa plugin:

After opening, press the “Start” button within the plugin:

You will see the tool scanning for changes regularly.