### QuickStart: Setting up and using Apache Tribes Channel

Source: https://github.com/apache/tomcat/blob/main/java/org/apache/catalina/tribes/package.html

This example demonstrates the basic steps to create, configure, and start a GroupChannel, attach listeners, send a message, and retrieve cluster members. Ensure that message objects implement java.io.Serializable or java.io.Externalizable.

```java
Channel myChannel = new GroupChannel();

MyMessageListener msgListener = new MyMessageListener();
MyMemberListener mbrListener = new MyMemberListener();

myChannel.addMembershipListener(mbrListener);
myChannel.addChannelListener(msgListener);

myChannel.start(Channel.DEFAULT);

Serializable myMsg = new MyMessage();

Member[] group = myChannel.getMembers();

channel.send(group,myMsg,Channel.SEND_OPTIONS_DEFAULT);
```

--------------------------------

### Start Tomcat on *nix

Source: https://github.com/apache/tomcat/blob/main/RUNNING.txt

Commands to start Tomcat on *nix systems using either startup.sh or catalina.sh start.

```shell
$CATALINA_HOME/bin/startup.sh
```

```shell
$CATALINA_HOME/bin/catalina.sh start
```

--------------------------------

### Start Tomcat on Windows

Source: https://github.com/apache/tomcat/blob/main/RUNNING.txt

Commands to start Tomcat on Windows using either startup.bat or catalina.bat start.

```batch
%CATALINA_HOME%\bin\startup.bat
```

```batch
%CATALINA_HOME%\bin\catalina.bat start
```

--------------------------------

### Install Application to Servlet Container

Source: https://github.com/apache/tomcat/blob/main/webapps/docs/appdev/build.xml.txt

Installs the web application to a specified Tomcat installation using the manager URL. This target requires the 'compile' target to be executed first and must be run on the same server as Tomcat.

```xml
<target name="install" depends="compile"
   description="Install application to servlet container">

    <deploy url="${manager.url}"
       username="${manager.username}"
       password="${manager.password}"
           path="${app.path}"
       localWar="file://${build.home}"/>

  </target>
```

--------------------------------

### Configure JRE_HOME and CATALINA_PID on *nix

Source: https://github.com/apache/tomcat/blob/main/RUNNING.txt

Example of a setenv.sh script to configure JRE_HOME and CATALINA_PID. Ensure the script is placed in $CATALINA_BASE/bin.

```shell
JRE_HOME=/usr/java/latest
CATALINA_PID="/run/tomcat.pid"
```

--------------------------------

### Run Default Tomcat Build

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Navigate to the Tomcat source directory and execute the 'ant' command to run the default 'deploy' target. This builds a usable Tomcat installation in the 'output/build' directory.

```bash
cd ${tomcat.source}
ant
```

--------------------------------

### Build NSIS Installer Locally

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Build the NSIS installer locally using the 'local-makensis' Ant target. This is an alternative to using Wine for creating reproducible installers.

```bash
ant local-makensis
```

--------------------------------

### Changelog Entry Examples

Source: https://github.com/apache/tomcat/blob/main/CONTRIBUTING.md

Examples of changelog entries using specific XML elements for different types of changes. Ensure entries are concise, use present tense, and include code tags for technical terms.

```xml
<add>Add support for Jakarta EE 12 XML schemas.</add>
```

```xml
<update>Change the default for encodedSolidusHandling from decode to reject.</update>
```

```xml
<bug>70000</bug>: Fix duplication of special headers in the response after commit.
```

```xml
<scode>Refactor generation of the remote user element in the access log to remove unnecessary code.</scode>
```

```xml
<docs>Add Javadoc for the Common Annotations API implementation.</docs>
```

--------------------------------

### IDE Setup with Ant Targets

Source: https://github.com/apache/tomcat/blob/main/CONTRIBUTING.md

Execute these Ant targets to set up IDE-specific configuration files after checking out the Tomcat sources. Re-run after switching branches or pulling changes to keep configurations in sync.

```bash
ant ide-eclipse
```

```bash
ant ide-intellij
```

```bash
ant ide-netbeans
```

--------------------------------

### Configure JRE_HOME and CATALINA_PID on Windows

Source: https://github.com/apache/tomcat/blob/main/RUNNING.txt

Example of a setenv.bat script to configure JRE_HOME and CATALINA_PID. Ensure the script is placed in %CATALINA_BASE%\bin.

```batch
set "JRE_HOME=%ProgramFiles%\Java\jre@MIN_JAVA_VERSION@"
exit /b 0
```

--------------------------------

### List Installed Applications

Source: https://github.com/apache/tomcat/blob/main/webapps/docs/appdev/build.xml.txt

Lists the currently running web applications on a specified Tomcat installation. This target is useful for verifying if an application has been successfully installed.

```xml
<target name="list"
   description="List installed applications on servlet container">

    <list    url="${manager.url}"
        username="${manager.username}"
        password="${manager.password}"/>

  </target>
```

--------------------------------

### Configure Code Signing Service

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Enable and configure the code signing service for Windows installers by setting relevant properties in build.properties. Credentials for the service are provided by the PMC.

```properties
do.codesigning=true
codesigning.storepass=request-via-pmc
codesigning.keypass=request-via-pmc
```

--------------------------------

### Download NSIS Distribution

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Download the NSIS distribution using the 'download-dist' Ant target. The installation path is typically found in 'nsis.bin.home' in build.properties.default.

```bash
ant download-dist
```

--------------------------------

### Create a Custom RuleSet for Digester

Source: https://github.com/apache/tomcat/blob/main/java/org/apache/tomcat/util/digester/package.html

Implement the RuleSet interface to encapsulate a set of rules for reuse. This example shows how to define rules and associate them with a namespace and an optional prefix.

```java
public class MyRuleSet extends RuleSetBase {

  public MyRuleSet() {
    this("");
  }

  public MyRuleSet(String prefix) {
    super();
    this.prefix = prefix;
    this.namespaceURI = "http://www.mycompany.com/MyNamespace";
  }

  protected String prefix = null;

  public void addRuleInstances(Digester digester) {
    digester.addObjectCreate(prefix + "foo/bar",
      "com.mycompany.MyFoo");
    digester.addSetProperties(prefix + "foo/bar");
  }

}
```

--------------------------------

### RequestInfo Servlet Implementation

Source: https://github.com/apache/tomcat/blob/main/webapps/examples/servlets/reqinfo.html

This Java servlet extends HttpServlet to process incoming requests. It sets the content type to HTML and writes request details to the response. It handles GET requests by default and forwards POST requests to the doGet method.

```java
import java.io.*;
import jakarta.servlet.*;
import jakarta.servlet.http.*;

public class RequestInfo extends HttpServlet {

    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        response.setContentType("text/html");
        PrintWriter out = response.getWriter();
        out.println("<html>");
        out.println("<body>");
        out.println("<head>");
        out.println("<title>Request Information Example</title>");
        out.println("</head>");
        out.println("<body>");
        out.println("<h3>Request Information Example</h3>");
        out.println("Method: " + request.getMethod());
        out.println("Request URI: " + request.getRequestURI());
        out.println("Protocol: " + request.getProtocol());
        out.println("PathInfo: " + request.getPathInfo());
        out.println("Remote Address: " + request.getRemoteAddr());
        out.println("</body>");
        out.println("</html>");
    }

    /**
     * We are going to perform the same operations for POST requests
     * as for GET methods, so this method just sends the request to
     * the doGet method.
     */

    public void doPost(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        doGet(request, response);
    }
}
```

--------------------------------

### Prepare Build Directory

Source: https://github.com/apache/tomcat/blob/main/webapps/docs/appdev/build.xml.txt

Creates the necessary build directories and copies static content for the web application. This target is typically executed indirectly.

```xml
<target name="prepare">

    <!-- Create build directories as needed -->
    <mkdir  dir="${build.home}"/>
    <mkdir  dir="${build.home}/WEB-INF"/>
    <mkdir  dir="${build.home}/WEB-INF/classes"/>


    <!-- Copy static content of this web application -->
    <copy todir="${build.home}">
      <fileset dir="${web.home}"/>
    </copy>

    <!-- Copy external dependencies as required -->
    <!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
    <mkdir  dir="${build.home}/WEB-INF/lib"/>

```

--------------------------------

### Java Servlet: HelloWorld

Source: https://github.com/apache/tomcat/blob/main/webapps/examples/servlets/helloworld.html

Implement a simple servlet that returns an HTML page. Ensure necessary imports for Jakarta Servlet API.

```java
import java.io.*;
import jakarta.servlet.*;
import jakarta.servlet.http.*;

public class HelloWorld extends HttpServlet {

    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        response.setContentType("text/html");
        PrintWriter out = response.getWriter();
        out.println("<html>");
        out.println("<head>");
        out.println("<title>Hello World!</title>");
        out.println("</head>");
        out.println("<body>");
        out.println("<h1>Hello World!</h1>");
        out.println("</body>");
        out.println("</html>");
    }
}
```

--------------------------------

### Build Tomcat Documentation

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Execute the 'build-docs' Ant target to quickly build the documentation web application. The output will be located in 'output/build/webapps/docs'.

```bash
cd ${tomcat.source}
ant build-docs
```

--------------------------------

### Unpack WAR File with Jar Command

Source: https://github.com/apache/tomcat/blob/main/webapps/docs/appdev/sample/index.html

Use this command to unpack the sample WAR file if you wish to browse its contents directly. Ensure you are in the directory containing the sample.war file.

```bash
jar -xvf sample.war
```

--------------------------------

### Request Parameter Handling Servlet (Java)

Source: https://github.com/apache/tomcat/blob/main/webapps/examples/servlets/reqparams.html

This servlet retrieves 'firstname' and 'lastname' parameters from the request. It handles both GET and POST requests, displaying the parameters or a form to submit them. Ensure HTMLFilter is available for security.

```java
import java.io.*;
import java.util.*;
import jakarta.servlet.*;
import jakarta.servlet.http.*;

public class RequestParamExample extends HttpServlet {

    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        response.setContentType("text/html");
        PrintWriter out = response.getWriter();
        out.println("<html>");
        out.println("<head>");
        out.println("<title>Request Parameters Example</title>");
        out.println("</head>");
        out.println("<body>");
        out.println("<h3>Request Parameters Example</h3>");
        out.println("Parameters in this request:<br>");

        String firstName = request.getParameter("firstname");
        String lastName = request.getParameter("lastname");

        if (firstName != null || lastName != null) {
            out.println("First Name:");
            out.println(" = " + HTMLFilter.filter(firstName) + "<br>");
            out.println("Last Name:");
            out.println(" = " + HTMLFilter.filter(lastName));
        } else {
            out.println("No Parameters, Please enter some");
        }
        out.println("<P>");
        out.print("<form action=\"");
        out.print("RequestParamExample\" ");
        out.println("method=POST>");
        out.println("First Name:");
        out.println("<input type=text size=20 name=firstname>");
        out.println("<br>");
        out.println("Last Name:");
        out.println("<input type=text size=20 name=lastname>");
        out.println("<br>");
        out.println("<input type=submit>");
        out.println("</form>");
        out.println("</body>");
        out.println("</html>");
    }

    public void doPost(HttpServletRequest request, HttpServletResponse res)
    throws IOException, ServletException
    {
        doGet(request, response);
    }
}
```

--------------------------------

### Using ExtendedBaseRules in Digester

Source: https://github.com/apache/tomcat/blob/main/java/org/apache/tomcat/util/digester/package.html

Demonstrates how to set a custom Rules implementation, ExtendedBaseRules, for Digester initialization to leverage its enhanced pattern matching syntax.

```java
Digester digester = ...
  ...
  digester.setRules(new ExtendedBaseRules());
  ...
```

--------------------------------

### Build Javadoc API Documentation

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Run the 'javadoc' Ant target to build the API documentation separately. The generated Javadoc will be found in specific output directories.

```bash
cd ${tomcat.source}
ant javadoc
```

--------------------------------

### Java Servlet for Session Management

Source: https://github.com/apache/tomcat/blob/main/webapps/examples/servlets/sessions.html

This servlet handles GET requests to manage user sessions. It creates a new session if one doesn't exist, retrieves session creation and last access times, and allows setting and retrieving session attributes via request parameters.

```java
import java.io.*;
import java.util.*;
import jakarta.servlet.*;
import jakarta.servlet.http.*;

public class SessionExample extends HttpServlet {

    public void doGet(HttpServletRequest request, HttpServletResponse response)
    throws IOException, ServletException
    {
        response.setContentType("text/html");
        PrintWriter out = response.getWriter();

        HttpSession session = request.getSession(true);

        // print session info

        Date created = new Date(session.getCreationTime());
        Date accessed = new Date(session.getLastAccessedTime());
        out.println("ID " + session.getId());
        out.println("Created: " + created);
        out.println("Last Accessed: " + accessed);

        // set session info if needed

        String dataName = request.getParameter("dataName");
        if (dataName != null && dataName.length() > 0) {
            String dataValue = request.getParameter("dataValue");
            session.setAttribute(dataName, dataValue);
        }

        // print session contents

        Enumeration e = session.getAttributeNames();
        while (e.hasMoreElements()) {
            String name = (String)e.nextElement();
            String value = session.getAttribute(name).toString();
            out.println(name + " \= " + value);
        }
    }
}
```

--------------------------------

### Create Binary Distribution

Source: https://github.com/apache/tomcat/blob/main/webapps/docs/appdev/build.xml.txt

Creates a binary distribution of the web application, including Javadoc and a WAR file. This target depends on 'compile' and 'javadoc'.

```xml
<target name="dist" depends="compile,javadoc"
   description="Create binary distribution">

    <!-- Copy documentation subdirectories -->
    <mkdir   dir="${dist.home}/docs"/>
    <copy    todir="${dist.home}/docs">
      <fileset dir="${docs.home}"/>
    </copy>

    <!-- Create application JAR file -->
    <jar jarfile="${dist.home}/${app.name}-${app.version}.war"
         basedir="${build.home}"/>

    <!-- Copy additional files to ${dist.home} as necessary -->

  </target>
```

--------------------------------

### Configure Base Path for Dependencies

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Specify the directory for downloading dependency binaries by setting the 'base.path' property in 'build.properties'. This helps avoid re-downloading libraries.

```properties
base.path=/home/me/some-place-to-download-to
```

--------------------------------

### Maven Build Command

Source: https://github.com/apache/tomcat/blob/main/modules/stuffed/README.md

Use this command to clean and package the Tomcat distribution with Maven.

```bash
mvn clean; mvn package
```

--------------------------------

### Build an Official Tomcat Release

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Reproduce an official build using the defined build tool chain. Navigate to the source directory and execute the 'release' target with Ant.

```bash
cd ${tomcat.source}
ant release
```

--------------------------------

### Docker Build Command

Source: https://github.com/apache/tomcat/blob/main/modules/stuffed/README.md

Build a Docker image for the Apache Tomcat stuffed distribution. Customize the tag and Dockerfile path as needed.

```bash
docker build -t apache/tomcat-stuffed:1.0 -f ./Dockerfile .
```

--------------------------------

### Generate Full OpenSSL API with jextract

Source: https://github.com/apache/tomcat/blob/main/res/openssl/README.md

Generate the full OpenSSL API using jextract for development purposes. This command includes source generation, specifies the package name, links the SSL library, and defines the include path and output directory.

```bash
$JEXTRACT_HOME/bin/jextract --source -t org.apache.tomcat.util.openssl -lssl -I /usr/lib/gcc/x86_64-redhat-linux/14/include openssl.h --output src/main/java
```

--------------------------------

### Generate NetBeans Project Configuration

Source: https://github.com/apache/tomcat/blob/main/res/ide-support/netbeans/README.txt

Run this Ant target to create the nbproject directory and default configuration files for NetBeans integration.

```bash
ant ide-netbeans
```

--------------------------------

### Build Release Artifacts with Ant

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Execute the Ant targets for creating a release build. This sequence includes pre-release checks, the main release build, and Git operations for tagging and pushing.

```bash
cd ${tomcat.source}
ant pre-release
ant release
git commit -a -m "Tag <version-number>"
git tag <vesion-number>
git push origin <version-number>
ant release
git reset --hard HEAD~1
```

--------------------------------

### Build Tomcat Extras Components

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Use the 'extras' Ant target to build additional components like commons-logging and webservices. These are typically built during a 'release' build.

```bash
cd ${tomcat.source}
ant extras
```

--------------------------------

### Initialize Digester with a Custom RuleSet

Source: https://github.com/apache/tomcat/blob/main/java/org/apache/tomcat/util/digester/package.html

Register a custom RuleSet with a Digester instance to apply its defined rules. This demonstrates how to use a RuleSet to configure the Digester for XML processing.

```java
Digester digester = new Digester();
... configure Digester properties ...
digester.addRuleSet(new MyRuleSet("baz/"));
```

--------------------------------

### Initialize Digester Instance

Source: https://github.com/apache/tomcat/blob/main/java/org/apache/tomcat/util/digester/package.html

Creates a new Digester instance and configures it for validating XML parsing. The controller servlet is pushed onto the stack to track configured objects.

```java
Digester digester = new Digester();
digester.push(this); // Push controller servlet onto the stack
digester.setValidating(true);
```

--------------------------------

### Configure GPG Executable for Signing

Source: https://github.com/apache/tomcat/blob/main/BUILDING.txt

Specify the path to the GPG executable in build.properties for cryptographic signing of release artifacts. This is used by both the release build and the 'verify-release' Ant target.

```properties
gpg.exec=/path/to/gpg
```

--------------------------------

### Compile Java Sources

Source: https://github.com/apache/tomcat/blob/main/webapps/docs/appdev/build.xml.txt

Compiles Java source files and copies application resources to the build directory. Ensure the build.home directory is prepared before running this target.

```xml
<target name="compile" depends="prepare"
   description="Compile Java sources">

    <!-- Compile Java classes as necessary -->
    <mkdir    dir="${build.home}/WEB-INF/classes"/>
    <javac srcdir="${src.home}"
          destdir="${build.home}/WEB-INF/classes"
            debug="${compile.debug}"
      deprecation="${compile.deprecation}">
        <classpath refid="compile.classpath"/>
    </javac>

    <!-- Copy application resources -->
    <copy  todir="${build.home}/WEB-INF/classes">
      <fileset dir="${src.home}" excludes="**/*.java"/>
    </copy>

  </target>
```

--------------------------------

### Configure Tomcat Context XML

Source: https://github.com/apache/tomcat/blob/main/RUNNING.txt

This XML snippet shows how to configure a Tomcat context, specifying the docBase and including a RemoteCIDRValve for access control. It demonstrates referencing CATALINA_HOME.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="${catalina.home}/webapps/manager"
  antiResourceLocking="false" privileged="true" >
<Valve className="org.apache.catalina.valves.RemoteCIDRValve"
       allow="127.0.0.0/8,::1/128" />
    <Manager sessionAttributeValueClassNameFilter="java\.lang\.(?:Boolean|Integer|Long|Number|String)|org\.apache\.catalina\.filters\.CsrfPreventionFilter\$LruCache(?:\$1)?|java\.util\.(?:Linked)?HashMap"/>
  </Context>
```

--------------------------------

### Using RegexRules with SimpleRegexMatcher in Digester

Source: https://github.com/apache/tomcat/blob/main/java/org/apache/tomcat/util/digester/package.html

Shows how to configure Digester with RegexRules and a SimpleRegexMatcher for advanced pattern matching based on regular expressions. This differs from the default by returning all matching rules.

```java
Digester digester = ...
  ...
  digester.setRules(new RegexRules(new SimpleRegexMatcher()));
  ...
```

--------------------------------

### Generate OpenSSL API Support Classes with jextract

Source: https://github.com/apache/tomcat/blob/main/res/openssl/README.md

Use jextract to generate a trimmed-down OpenSSL API based on the openssl-tomcat.conf configuration. Ensure JEXTRACT_HOME is set and the correct include path is provided.

```bash
$JEXTRACT_HOME/bin/jextract @openssl-tomcat.conf openssl.h
```