| --- |
| layout: howTo |
| --- |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <!-- Main --> |
| <div id="main"> |
| |
| <!-- Introduction --> |
| <section id="intro" class="main special"> |
| <div class=""> |
| <div class="content align-left"> |
| <header class="major"> |
| <h1><b>Configure Custom WebAdmin routes</b></h1> |
| </header> |
| |
| <p> |
| The current project demonstrates how to write custom webadmin routes for Apache James. This enables writing new |
| administrative features exposed over a REST API. This can allow you to write some additional features, make James |
| interact with third party systems, do advance reporting... |
| </p> |
| |
| <p> |
| Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-webadmin-route">GitHub</a>. |
| </p> |
| |
| <p> |
| Start by importing the dependencies: |
| </p> |
| |
| <pre><code><dependency> |
| <groupId>org.apache.james</groupId> |
| <artifactId>james-server-webadmin-core</artifactId> |
| </dependency> |
| </code></pre> |
| |
| <p>You can then write your first route using the <a href="https://sparkjava.com/">Spark Java</a> framework:</p> |
| |
| <pre><code>public class RouteA implements Routes { |
| @Override |
| public String getBasePath() { |
| return "/hello/a"; |
| } |
| |
| @Override |
| public void define(Service service) { |
| service.get(getBasePath(), (req, res) -> "RouteA\n"); |
| } |
| }</code></pre> |
| |
| <ul>Knowing that: |
| <li>entending <b>Routes</b>: will ensure that authentication is requested if configured.</li> |
| <li>entending <b>PublicRoutes</b>: will not request authentication.</li> |
| </ul> |
| |
| <p>You can compile this example project:</p> |
| |
| <pre><code>mvn clean install</code></pre> |
| |
| <p>Then embed your route into a James server. First configure your route into <code>webadmin.properties</code>:</p> |
| |
| <pre><code>enabled=true |
| port=8000 |
| host=localhost |
| |
| # List of fully qualified class names that should be exposed over webadmin |
| # in addition to your product default routes. Routes needs to be located |
| # within the classpath or in the ./extensions-jars folder. |
| extensions.routes=org.apache.james.examples.RouteA</code></pre> |
| |
| <p>Then start a James server with your JAR and the configuration:</p> |
| |
| <pre><code>docker run -d \ |
| -v $PWD/webadmin.properties:/root/conf/webadmin.properties \ |
| -v $PWD/exts:/root/extensions-jars \ |
| -p 25:25 \ |
| apache/james:memory-latest --generate-keystore</code></pre> |
| |
| <p>You can play with <code>curl</code> utility with the resulting server:</p> |
| |
| <pre><code>$ curl -XGET http://172.17.0.2:8000/hello/a |
| RouteA</code></pre> |
| </div> |
| <footer class="major"> |
| <ul class="actions align-center"> |
| <li><a href="index.html" class="button">go back to other how-tos</a></li> |
| </ul> |
| </footer> |
| </div> |
| </section> |
| |
| </div> |