Browse Source

Add readme

tags/v2.0.0
parent
commit
eb00e4103e
1 changed files with 89 additions and 0 deletions
  1. +89
    -0
      README.md

+ 89
- 0
README.md View File

@@ -0,0 +1,89 @@
# Webable

Abstraction over embedding servlet containers.

## Introduction

Webable offers easy programmatic creation of embedded servlet containers, such as [Tomcat](https://tomcat.apache.org/)
or [Jetty](https://www.eclipse.org/jetty/), with unified, builder-like API.

Webable also offers optional "handler" configuration, which is its own API on top of servlets/filters, which
allows easier and more functional approach to HTTP request handling.

Supported containers:
* [Tomcat](https://tomcat.apache.org/)
* [Jetty](https://www.eclipse.org/jetty/)
* [Undertow](http://undertow.io/)


## Including as dependency

Add dependencies in your ``pom.xml``:

```xml
<dependency>
<groupId>org.perfectable</groupId>
<artifactId>webable-api</artifactId>
<version>${webable.version}</version>
</dependency>
<dependency>
<groupId>org.perfectable</groupId>
<artifactId>webable-tomcat</artifactId>
<version>${webable.version}</version>
<scope>runtime</scope>
</dependency>
```

Replace ``webable-tomcat`` with ``webable-jetty`` or ``webable-undertow`` if you need other container.

Note: you need to have actual container library in ``runtime`` scope only.

If you want to use functional request handlers, add also:

```xml
<dependency>
<groupId>org.perfectable</groupId>
<artifactId>webable-handler</artifactId>
<version>${webable.version}</version>
</dependency>
```

## Use example

Plain servlet-based webapplication:

```java
WebApplication.begin()
.withPort(8000)
.withContextParameter("applicationUrl", "http://example.org/")
.withForcedSessionCreation()
.withHttpSessionListener(InjectContextListener.INSTANCE)
.withWebsocketEndpoint(ServerEndpointConfig.Builder.create(WebsocketEndpoint.class, "/ws").build())
.withFilter(BasicAuthenticationFilter.create(userNameResolver))
.named("basicAuth")
.mappedTo("/*")
.endFilter()
.withServlet(EntryServlet.class)
.initialParameter("performer", userName)
.mappedTo("/")
.loadedInitially()
.endServlet()
.serveBlocking();
```

Functional request-handlers:

```java
ResourceResolver scriptsResolver = path ->
StreamResourceLoader.classpathFromPath(path).as(MediaType.JAVASCRIPT_UTF_8);
RequestHandler rootHandler = request -> HttpResponse.status(HttpStatus.FOUND)
.withHeader("Location", "/").withPlainTextContent("Hello " + request.completePath())
WebApplication.begin()
.withPort("10.0.0.1", 80)
.extend(HandlerServerConfigurationExtension.INSTANCE.adjustType())
.withGlobalChannel(BasicAuthenticationRequestChannel.of(authenticator))
.withResources("/scripts/*", scriptsResolver)
.withResponse("", HttpResponse.OK.withResourceContent(MediaType.XHTML_UTF_8, "index.html"))
.withRootHandler(rootHandler)
.serveBlocking();
```

Loading…
Cancel
Save