CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-javax--javaee-api

Complete Java Enterprise Edition 8 specification APIs providing all standardized enterprise application development interfaces

—

Pending
Overview
Eval results
Files

rest-services.mddocs/

RESTful Web Services

JAX-RS API for building RESTful web services with annotation-driven development, comprehensive client API, and support for JSON/XML processing.

Core Annotations

HTTP Method Annotations

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("GET")
public @interface GET;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("POST")
public @interface POST;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("PUT")
public @interface PUT;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("DELETE")
public @interface DELETE;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("HEAD")
public @interface HEAD;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("OPTIONS")
public @interface OPTIONS;

Path and Parameter Annotations

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Path {
    String value();
}

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface PathParam {
    String value();
}

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface QueryParam {
    String value();
}

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface HeaderParam {
    String value();
}

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface FormParam {
    String value();
}

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface MatrixParam {
    String value();
}

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface CookieParam {
    String value();
}

Content Type Annotations

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Produces {
    String[] value() default {};
}

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Consumes {
    String[] value() default {};
}

Response Handling

Response

public abstract class Response implements Closeable {
    public abstract int getStatus();
    public abstract StatusType getStatusInfo();
    public abstract Object getEntity();
    public abstract <T> T readEntity(Class<T> entityType);
    public abstract <T> T readEntity(GenericType<T> entityType);
    public abstract <T> T readEntity(Class<T> entityType, Annotation[] annotations);
    public abstract <T> T readEntity(GenericType<T> entityType, Annotation[] annotations);
    public abstract boolean hasEntity();
    public abstract boolean bufferEntity();
    public abstract void close();
    public abstract MultivaluedMap<String, Object> getMetadata();
    public abstract MultivaluedMap<String, String> getStringHeaders();
    public abstract String getHeaderString(String name);
    
    public static ResponseBuilder status(Status status);
    public static ResponseBuilder status(int status);
    public static ResponseBuilder ok();
    public static ResponseBuilder ok(Object entity);
    public static ResponseBuilder ok(Object entity, MediaType type);
    public static ResponseBuilder ok(Object entity, String type);
    public static ResponseBuilder serverError();
    public static ResponseBuilder created(URI location);
    public static ResponseBuilder accepted();
    public static ResponseBuilder accepted(Object entity);
    public static ResponseBuilder noContent();
    public static ResponseBuilder notModified();
    public static ResponseBuilder notModified(EntityTag tag);
    public static ResponseBuilder notModified(String tag);
    public static ResponseBuilder seeOther(URI location);
    public static ResponseBuilder temporaryRedirect(URI location);
    public static ResponseBuilder notAcceptable(List<Variant> variants);
    public static Response fromResponse(Response response);
}

ResponseBuilder

public static abstract class ResponseBuilder {
    public abstract Response build();
    public abstract ResponseBuilder clone();
    public abstract ResponseBuilder status(int status);
    public abstract ResponseBuilder status(Status status);
    public abstract ResponseBuilder status(StatusType status);
    public abstract ResponseBuilder entity(Object entity);
    public abstract ResponseBuilder allow(String... methods);
    public abstract ResponseBuilder allow(Set<String> methods);
    public abstract ResponseBuilder cacheControl(CacheControl cacheControl);
    public abstract ResponseBuilder encoding(String encoding);
    public abstract ResponseBuilder header(String name, Object value);
    public abstract ResponseBuilder replaceAll(MultivaluedMap<String, Object> headers);
    public abstract ResponseBuilder language(String language);
    public abstract ResponseBuilder language(Locale language);
    public abstract ResponseBuilder location(URI location);
    public abstract ResponseBuilder contentLocation(URI location);
    public abstract ResponseBuilder tag(EntityTag tag);
    public abstract ResponseBuilder tag(String tag);
    public abstract ResponseBuilder lastModified(Date lastModified);
    public abstract ResponseBuilder expires(Date expires);
    public abstract ResponseBuilder cookie(NewCookie... cookies);
}

Context Injection

Context Annotations

@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Context;

UriInfo

public interface UriInfo {
    String getPath();
    String getPath(boolean decode);
    List<PathSegment> getPathSegments();
    List<PathSegment> getPathSegments(boolean decode);
    URI getRequestUri();
    UriBuilder getRequestUriBuilder();
    URI getAbsolutePath();
    UriBuilder getAbsolutePathBuilder();
    URI getBaseUri();
    UriBuilder getBaseUriBuilder();
    MultivaluedMap<String, String> getPathParameters();
    MultivaluedMap<String, String> getPathParameters(boolean decode);
    MultivaluedMap<String, String> getQueryParameters();
    MultivaluedMap<String, String> getQueryParameters(boolean decode);
    List<String> getMatchedURIs();
    List<String> getMatchedURIs(boolean decode);
    List<Object> getMatchedResources();
    URI resolve(URI uri);
    URI relativize(URI uri);
}

HttpHeaders

public interface HttpHeaders {
    List<String> getRequestHeader(String name);
    String getHeaderString(String name);
    MultivaluedMap<String, String> getRequestHeaders();
    List<MediaType> getAcceptableMediaTypes();
    List<Locale> getAcceptableLanguages();
    MediaType getMediaType();
    Locale getLanguage();
    Map<String, Cookie> getCookies();
    Date getDate();
    int getLength();
}

SecurityContext

public interface SecurityContext {
    Principal getUserPrincipal();
    boolean isUserInRole(String role);
    boolean isSecure();
    String getAuthenticationScheme();
    
    String BASIC_AUTH = "BASIC";
    String FORM_AUTH = "FORM";
    String CLIENT_CERT_AUTH = "CLIENT_CERT";
    String DIGEST_AUTH = "DIGEST";
}

Client API

Client

public interface Client extends Configurable<Client>, AutoCloseable {
    void close();
    WebTarget target(String uri);
    WebTarget target(URI uri);
    WebTarget target(UriBuilder uriBuilder);
    Invocation.Builder invocation(Link link);
}

WebTarget

public interface WebTarget extends Configurable<WebTarget> {
    URI getUri();
    UriBuilder getUriBuilder();
    WebTarget path(String path);
    WebTarget resolveTemplate(String name, Object value);
    WebTarget resolveTemplate(String name, Object value, boolean encodeSlashInPath);
    WebTarget resolveTemplateFromEncoded(String name, Object value);
    WebTarget resolveTemplates(Map<String, Object> templateValues);
    WebTarget resolveTemplates(Map<String, Object> templateValues, boolean encodeSlashInPath);
    WebTarget resolveTemplatesFromEncoded(Map<String, Object> templateValues);
    WebTarget matrixParam(String name, Object... values);
    WebTarget queryParam(String name, Object... values);
    Invocation.Builder request();
    Invocation.Builder request(String... acceptedResponseTypes);
    Invocation.Builder request(MediaType... acceptedResponseTypes);
}

Invocation.Builder

public static interface Builder extends SyncInvoker, AsyncInvoker {
    Invocation build(String method);
    Invocation build(String method, Entity<?> entity);
    Invocation buildGet();
    Invocation buildDelete();
    Invocation buildPost(Entity<?> entity);
    Invocation buildPut(Entity<?> entity);
    AsyncInvoker async();
    Invocation.Builder accept(String... mediaTypes);
    Invocation.Builder accept(MediaType... mediaTypes);
    Invocation.Builder acceptLanguage(Locale... locales);
    Invocation.Builder acceptLanguage(String... locales);
    Invocation.Builder acceptEncoding(String... encodings);
    Invocation.Builder cookie(Cookie cookie);
    Invocation.Builder cookie(String name, String value);
    Invocation.Builder cacheControl(CacheControl cacheControl);
    Invocation.Builder header(String name, Object value);
    Invocation.Builder headers(MultivaluedMap<String, Object> headers);
    Invocation.Builder property(String name, Object value);
}

Application Configuration

Application

public abstract class Application {
    public Set<Class<?>> getClasses();
    public Set<Object> getSingletons();
    public Map<String, Object> getProperties();
}

ApplicationPath

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApplicationPath {
    String value();
}

Media Types

MediaType

public class MediaType {
    public static final String WILDCARD = "*/*";
    public static final String APPLICATION_XML = "application/xml";
    public static final String APPLICATION_ATOM_XML = "application/atom+xml";
    public static final String APPLICATION_XHTML_XML = "application/xhtml+xml";
    public static final String APPLICATION_SVG_XML = "application/svg+xml";
    public static final String APPLICATION_JSON = "application/json";
    public static final String APPLICATION_FORM_URLENCODED = "application/x-www-form-urlencoded";
    public static final String MULTIPART_FORM_DATA = "multipart/form-data";
    public static final String APPLICATION_OCTET_STREAM = "application/octet-stream";
    public static final String TEXT_PLAIN = "text/plain";
    public static final String TEXT_XML = "text/xml";
    public static final String TEXT_HTML = "text/html";
    
    public static final MediaType WILDCARD_TYPE = new MediaType();
    public static final MediaType APPLICATION_XML_TYPE = new MediaType("application", "xml");
    public static final MediaType APPLICATION_JSON_TYPE = new MediaType("application", "json");
    public static final MediaType TEXT_PLAIN_TYPE = new MediaType("text", "plain");
    public static final MediaType TEXT_HTML_TYPE = new MediaType("text", "html");
    
    public MediaType();
    public MediaType(String type, String subtype);
    public MediaType(String type, String subtype, Map<String, String> parameters);
    public MediaType(String type, String subtype, String charset);
    
    public String getType();
    public boolean isWildcardType();
    public String getSubtype();
    public boolean isWildcardSubtype();
    public Map<String, String> getParameters();
    public MediaType withCharset(String charset);
    public boolean isCompatible(MediaType other);
    public static MediaType valueOf(String type);
}

Usage Examples

Basic REST Resource

@Path("/users")
@ApplicationScoped
public class UserResource {
    
    @Inject
    private UserService userService;
    
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<User> getAllUsers() {
        return userService.findAll();
    }
    
    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Response getUser(@PathParam("id") Long id) {
        User user = userService.findById(id);
        if (user != null) {
            return Response.ok(user).build();
        } else {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
    }
    
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response createUser(User user, @Context UriInfo uriInfo) {
        User created = userService.create(user);
        URI location = uriInfo.getAbsolutePathBuilder()
                              .path(created.getId().toString())
                              .build();
        return Response.created(location).entity(created).build();
    }
    
    @PUT
    @Path("/{id}")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response updateUser(@PathParam("id") Long id, User user) {
        user.setId(id);
        User updated = userService.update(user);
        return Response.ok(updated).build();
    }
    
    @DELETE
    @Path("/{id}")
    public Response deleteUser(@PathParam("id") Long id) {
        userService.delete(id);
        return Response.noContent().build();
    }
}

JAX-RS Client Usage

// Create client and target
Client client = ClientBuilder.newClient();
WebTarget target = client.target("http://localhost:8080/api/users");

// GET request
List<User> users = target.request(MediaType.APPLICATION_JSON)
                         .get(new GenericType<List<User>>() {});

// POST request
User newUser = new User("John Doe", "john@example.com");
Response response = target.request()
                          .post(Entity.json(newUser));

// PUT request with path parameter
User updatedUser = new User("Jane Doe", "jane@example.com");
response = target.path("/{id}")
                 .resolveTemplate("id", 1)
                 .request()
                 .put(Entity.json(updatedUser));

// DELETE request
response = target.path("/{id}")
                 .resolveTemplate("id", 1)
                 .request()
                 .delete();

client.close();

Application Configuration

@ApplicationPath("/api")
public class RestApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> resources = new HashSet<>();
        resources.add(UserResource.class);
        resources.add(ProductResource.class);
        return resources;
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-javax--javaee-api

docs

dependency-injection.md

ejb.md

enterprise-services.md

index.md

json-processing.md

messaging.md

persistence.md

rest-services.md

security.md

transactions.md

validation.md

web-services.md

web-technologies.md

xml-binding.md

tile.json