korena's blog

Java web service structure

Standard toolkits and frameworks

Last updated: Februery 04th, 2016
server (Embedded Jetty)

Embedded jetty is the servlet container of choice for java based web services implementation at Siphyc, the reason being it's ease of deployment and development platform independence. Developers may use any familiar IDE or text editor for development and jump right into contributing to the project's progress, without the need for configuring a full blown servlet container or JavaEE compliant web server. The use of Jetty embedded server also facilitates fast deployment setup, as the deployment server machine requires only a working JVM and a properly setup firewall. To get started with this setup, refer to example service-base project

JAX-RS implementation (Jersey)

Jersey is an open source RESTful Web Services framework, it is the JAX-RS Reference Implementation, with a convenient test framework and extra goodies that facilitates developing RESTful Web services that seamlessly support exposing data in a variety of representation media types and abstracts away the low-level details of the client-server communication.

CDI implementation (WELD)

Context and dependency injection is a JCP standard that is a requirement for JavaEE compliance for Java server containers. Although we at Siphyc do not follow the Standards of JavaEE to the letter, we recognize the importance of CDI in all our Java web applications. For that we use WELD, which is the reference implementation for CDI: Contexts and Dependency Injection for the Java EE Platform.

JPA implementation (EclipseLink)

Java Persistence API is also A javaEE standard that is fully adopted and integrated into Siphyc's java based projects, we utilize EclipseLink implementation for it being the reference implementation for JPA standards. Note that in most complex setups, EclipseLink's Caching capabilities are disabled in favor of Memcached external server deployments.

Logging framework (SLF4J)

Development and build system

Last updated: Februery 04th, 2016
Maven build system

The build system of choice for all Siphyc java web service projects is Apache Maven, however, the most important restriction is that Maven build system should not be required for deployment, This basically means that for deployment, the system engineer should not need to rely on any maven plugin (such as jetty maven plugin) to be present in order to successfully deploy the web service application.

Source code structure

The recommended structure of the source code for java based web services is shown in the figure below.

├── misc
├── LICENSE.md
├── NOTICE.txt
├── pom.xml
├── README.md
└── src
    ├── main
    │   ├── java
    │   │   ├── com
    │   │   │   └── siphyc
    │   │   │       ├── binder
    │   │   │       │   └── AppJerseyBinder.java
    │   │   │       ├── dao
    │   │   │       ├── endpoints
    │   │   │       ├── filters
    │   │   │       ├── model
    │   │   │       ├── service
    │   │   │       ├── servlets
    │   │   │       └── utils
    │   │   │           └── Utilities.java
    │   │   └── JServer.java
    │   ├── resources
    │   │   ├── active.properties
    │   │   ├── connections
    │   │   │   └── conn.properties
    │   │   ├── development
    │   │   │   └── config.properties
    │   │   ├── staging
    │   │   │   └── config.properties
    │   │   ├── deployment
    │   │   │   └── config.properties
    │   │   ├── log4j.properties
    │   │   ├── logback.xml
    │   │   └── META-INF
    │   │       └── persistence.xml (optional)
    │   └── webapp
    │       ├── index.html
    │       └── WEB-INF
    │           ├── beans.xml
    │           ├── override-web.xml
    │           └── web.xml
    └── test
        ├── java
        │   └── com
        │       └── siphyc
        │           ├── mock
        │           │   ├── dao
        │           │   └── service
        │           └── test
        │               ├── app
        │               ├── dao
        │               ├── endpoints
        │               └── service
        │               └── servlets
        │               └── filters
        └── resources
            └── META-INF
                ├── beans.xml
                └── persistence.xml (optional)

misc directory: contains helpful scripts, reference documents ...
main/java/com/siphyc/endpoints: contain java classes for jersey based web service, the corresponding test path contains tests for those service classes.
test/java/com/siphyc/app: contains necessary context and server setup components for running tests outside of jetty embedded server.
Utilities.java: a convenience class for dealing with standard stuff like hashing, date formatting ...
JServer.java: The class containing the main method and setup code for Embedded Jetty server, placed on the Default Package (don't hate!)
AppJerseyBinder.java: a class extending Jersey's ResourceConfig, necessary for setting up Jersey.
conf.properties: maven profile specific configurations, used to define database resources, ports and deployment specific configurations.
conn.properties: a convenience configuration file that lists possible routes to be used as external resources used by this application, such as memcached server.
active.properties: the deployment configuration that will be used by the application.
App WAR structure

A successfully built application war package should resemble the following structure:

├── JServer.class
├── JNDI.properties
├── logback.xml
├── active.properties
├── META-INF
|   └── (Build specific information)
├── WEB-INF
|   ├── beans.xml
|   ├── override-web.xml
|   ├── web.xml
|   └── classes
|   |   ├── active.properties
|   |   ├── log4j.properties
|   |   ├── META-INF
|   |   |       └── (persistence information)
|   |   ├── (your application classes)
|   └── lib
|       └── (included libraries in app class path)
├── (any classes/jars required to be present in the server's class path)

Having the above WAR setup enables deployment by simply typing: ```language-bash java -jar app.war ``` in the command line (Linux)

Getting started

To quickly get started using this structure, read our example service-base post, you can also checkout the reference project code at Github service-base project and explore the source code. If you face any trouble setting up, you can contact the maintainer at korena@siphyc.com.