To establish a robust Java web development environment on macOS, begin by installing and configuring Apache Maven, a powerful build automation tool. This guide outlines the steps for a manual installation.

Maven Installation

First, download the Maven binary distribution. You can use curl for this:

curl -O https://dlcdn.apache.org/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz

After downloading, extract the archive to a suitable system-wide location, such as /usr/local. Adjust the version number as needed:

sudo tar -zxvf apache-maven-3.9.6-bin.tar.gz -C /usr/local 
sudo chown -R $(whoami):admin /usr/local/apache-maven-3.9.6

The chown command ensures your user has proper permissions to interact with the Maven installation directory.

Environment Variibles Configuration

To make Maven accessible from any terminal session, define the MAVEN_HOME and update your system's PATH. Edit your shell's profile file (e.g., ~/.zprofile for Zsh, or ~/.bash_profile for Bash):

vim ~/.zprofile

Add the following lines, replacing the path with your actual Maven installation directory:

export MAVEN_HOME=/usr/local/apache-maven-3.9.6
export PATH="${MAVEN_HOME}/bin:${PATH}"

After saving the file, apply the changes by sourcing your profile:

source ~/.zprofile

Verifying Maven Installation

Confirm that Maven is correctly installed and configured by checking its version:

mvn -v

This command should output details about your Maven, Java, and OS versions.

Configuring Maven Mirrors for Faster Downloads

For improved dependency download speeds, especially in certain geographical regions, it's recommended to configure a Maven mirror. Edit the settings.xml file located in the Maven installation's conf directory (/usr/local/apache-maven-3.9.6/conf/settings.xml). Locate the <mirrors> section and add the following entry, ensuring to comment out or remove any default active mirrors if they conflict:

<mirror>
  <id>aliyunmaven</id>
  <mirrorOf>*</mirrorOf>
  <name>Alibaba Cloud Public Maven Repository</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>

The <mirrorOf>*</mirrorOf> element directs all artifact requests to this configured mirror.

Customizing the Local Maven Repository Path

By default, Maven stores downloaded artifacts in ~/.m2/repository. To specify an alternative location, such as one within your Maven installation directory, modify the settings.xml file. Find or add the <localRepository> tag and set its value:

<localRepository>/usr/local/apache-maven-3.9.6/local_repo</localRepository>

Ensure the specified directory exists or Maven will create it upon first use.

Setting Up Apache Tomcat

Apache Tomcat is a widely used open-source web server and servlet container essential for deploying Java web applications. This section guides you through its installation and basic operation.

Tomcat Installation

Download the Tomcat 9 binary distribution using curl:

curl -O https://dlcdn.apache.org/tomcat/tomcat-9/v9.0.86/bin/apache-tomcat-9.0.86.tar.gz

Extract the archive to /usr/local and adjust ownership:

sudo tar -zxvf apache-tomcat-9.0.86.tar.gz -C /usr/local 
sudo chown -R $(whoami):admin /usr/local/apache-tomcat-9.0.86

Starting and Stopping Tomcat

Navigate to the Tomcat bin directory and execute the startup.sh script to launch the server:

cd /usr/local/apache-tomcat-9.0.86/bin
./startup.sh

Verify that Tomcat is running by opening a web browser and navigating to http://localhost:8080/. You should see the Tomcat welcome page.

To shut down the server, execute the shutdown.sh script from the same directory:

./shutdown.sh

Integrating with IntelliJ IDEA

For a streamlined development workflow, configure IntelliJ IDEA to use your newly installed Maven and Tomcat instances. In IDEA's settings (Preferences on macOS):

1. Maven Configuration: Go to Build, Execution, Deployment > Build Tools > Maven. Set the Maven home path to your /usr/local/apache-maven-3.9.6 directory. Ensure the User settings file points to your modified settings.xml (e.g., /usr/local/apache-maven-3.9.6/conf/settings.xml) and the Local repository matches the path you configured (e.g., /usr/local/apache-maven-3.9.6/local_repo).
2. Tomcat Server: Navigate to Build, Execution, Deployment > Application Servers and add a new Tomcat Server. Point it to your Tomcat installation directory.
3. Proxy Settings: If you are behind a corporate proxy, insure that IDEA's proxy setting are correctly configured, and check the option to "Use HTTP Proxy for Maven repositories" to allow Maven to resolve dependencies.
4. Automatic Directory Creation: When creating new Maven web projects, ensure that IDEA is configured to automatically generate necessary project directories (like src/main/webapp, src/main/java, etc.) to avoid manual setup issues.

Understanding Java Web Application Structure

A standard Maven-based Java web application project follows a specific directory structure within the Tomcat webapps directory, or when deployed as a WAR file:

<Tomcat_Installation_Dir>/webapps
└── your_webapp_name/             # This becomes the application context path (e.g., http://localhost:8080/your_webapp_name)
    ├── WEB-INF/                  # Mandatory directory for web application internal files
    │   ├── classes/              # Compiled Java servlets, utility classes, etc.
    │   ├── lib/                  # Application-specific JAR dependencies
    │   └── web.xml               # Deployment descriptor (defines servlets, mappings, filters, etc.)
    ├── index.html                # Default welcome page (can be .jsp or other)
    ├── static/                   # Static assets (CSS, JS, images)
    │   ├── css/
    │   │   └── style.css
    │   ├── js/
    │   └── img/
    └── ...                       # Other HTML, JSP, or static files

The WEB-INF directory is crucial; its contents are not directly accessible by clients, providing a secure place for configuration and compiled code.

Correcting web.xml Schema Issues in Maven Web Projects

Older Maven web project archetypes or manual configurations might generate web.xml files with outdated DTDs or XML schemas, leading to validation errors or compatibility issues with newer Servlet specifications. To ensure your web application uses a modern schema, replace the contents of your src/main/webapp/WEB-INF/web.xml with the following definition for Servlet API 4.0:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">
</web-app>

This snippet correctly defines the web application using the Java EE 8 (Servlet 4.0) schema, providing full compatibility with modern Tomcat versions and JAX-RS implementations. Always ensure your web.xml version aligns with your project's Servlet API dependency.