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:
Installation of “Environment Components” - which copies a JRE and Tomcat environment
Installation of “CaptainCasa Enterprise Client” - which copies the CaptainCasa .war files into this environment. And which copies other useful resources.
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.
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.
If you already have installed CaptainCasa then stop the corresponding Tomcat instances before installation.
Execute the setup of the environment components:
Start “setupRISC_JRE<version>Tomcat<version>.exe” that you downloaded from the CaptainCasa download page.
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.
Execute the setup of CaptaiNCasa Enterprise Client:
Start “setupRISC_V_S_YYYYMMDD.exe”
V = version
S = subversion
YYYYMMDD = Year/Month/Day of build
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.
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).
Either: Select “CC Enterprise Client RISC > A Start Server” from the Windows Start-Menu.
Or: Start “A_startserver.bat” from the installation directory.
Now start the browser showing the demo application:
Either: Select “CC Enterprise Client RISC > B Start Demo” from the Windows Start-Menu.
Or: Start “B_startclientRISC_demos.bat” from the installation directory
Or: Open URL “http://localhost:50000/demos/indexRISC.html” inside your web browser
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.
“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:
After starting one of the batch scripts a dialog pops up that asks if you want to allow “java.exe” to access the network. In this case grant access – if it's access to the “private” or to the “public” network is not relevant for CaptainCasa.
or: After starting one of the barch script you see an error message:
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.
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.
Either: Select “CC Enterprise Client RISC > C1 Start Tools Server” from the Windows Start-Menu.
Or: Start “C1_starttoolsserver.bat” from the installation directory.
Now start the browser showing the toolset application:
Either: Select “CC Enterprise Client RISC > C2 Start Tools Client” from the Windows Start-Menu.
Or: Start “C2_starttoolsRISC.bat” from the installation directory
Or: Open URL “http://localhost:51000/editor/indexRISC.html” inside your web browser
If you already have installed CaptainCasa then stop the corresponding Tomcat instances before installation.
Create a directory in which you want to place the CaptainCasa installation.
Extract the content of “EnterpriseClientRISC_JRE<version>Tomcat<version>.tar.gz” into this directory
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.
Execute the setup of CaptainCasa Enterprise Client:
Extract the content of “setupRISC_V_S_YYYYMMDD.tar.gz” into the same directory into which you installed the environment components.
V = version
S = subversion
YYYYMMDD = Year/Month/Day of build
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
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
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
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
...
All the batch files / shell scripts for starting certain aspects of Enterprise Client RISC are located in the main installation directory.
The server directory includes the JRE (Java Runtime Environment) for the server side processing and it includes 2 Tomcat instances:
“tomcat” - this is the Tomcat for the demo application and for the applications that you later on might build on your own.
“tomcattools” - this is the Tomcat for running the CaptainCasa toolset. The toolset is developed on base of CC Enterprise Client RISC, as well – so it requires some server. The tool-server is running as parallel instance to the demo/application server in order to decouple both.
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.
This is very simple:
Either: remove the existing content of the “/server/jre” directory and bring in the content of your Java environment (can be a JRE, can be a JDK). In this case all the batch files (Windows) / script files (Unix) can stay the same.
Or: exchange the *.bat (Windows) / *.sh (Windows) files so that the contained Java-home directory settings are pointing to your Java installation.
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:
Copy the exisiting “server/tomcat/” directory into “server/tomcat_cc”
Re-create the “server/tomcat/” directory and copy your Tomcat's files into the directory:
<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...
server/tomcat/conf/context.xml
Switch off the reloading by watching resources
Disable the persistence of sessions. Pay attention: for Tomcat 9 you need to uncomment things to disabled persistence, for Tomcat 10 you have to check if things are commented – carefully read the comments in the context.xml!
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>
server/tomcat/conf/server.xml
Use the ports: 50000 for http, 50001 for https, 50003 for shutdown
Example (Tomcat 10):
<Server port="50003" shutdown="SHUTDOWN">
...
<Connector port="50000" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="50001"
maxParameterCount="1000"
/>
server/tomcat/webapps/manager/WEB-INF/web.xml
Comment all parts that have to do with securing the manager application. (CaptainCasa tools are accessing the manager-application e.g. for triggering a re-deployment.)
IMPORTANT: this is only to be done in a development environment! NEVER deliver such configuration outside your development!
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>
In the “server/tomcat_cc” directory you may directly take a look at these files. For all 3 files you always see the modified file (e.g. “tomcat_cc/conf/server.xml”) and the original file (e.g. “tomcat_cc/conf/server.xml_original”) so that you can compare.
Finally: re-copy the “demos” web application from the “old” tomcat (server/tomcat_cc/webapps/demos) into the “new” one (server/tomcat/webapps/demos)
You now exchanged the Tomcat and – after some test run – can remove the “tomcat_cc” directory.
CaptainCasa comes with a little plugin to simplify the development with Eclipse.
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.
...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.
The plugin is part of the “/resources” folder, the name is “org.eclnt.eclipseplugin.zip”.
If using Eclipse <= 4.4 (Luna): Unzip the file into your eclipse installation directory.
Copy the .jar file contained in the zip-file into the /dropins-folder of your Eclipse installation directory.
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.