Interface | Description |
---|---|
HttpRestClient |
Extends a
RestClient to be capable of providing a User-Agent with
UserAgentAccessor.UserAgentMutator.setUserAgent(String) (HttpRestClient.withUserAgent(String) ) and to be
capable of using base URLs to be set with BaseUrlAccessor.BaseUrlMutator.setBaseUrl(String) (
BaseUrlAccessor.BaseUrlBuilder.withBaseUrl(String) ). |
HttpRestServer |
Extends a
RestServer to be capable of opening a server socket on the
local host with the provided port number via ConnectionOpenable.open(Object) or with an
additional maximum number of connections via HttpRestServer.open(Integer, int) . |
LoopbackRestClient |
Extends a
RestClient to be used as loopback device e.g. for testing
purposes such as testing your RestResponseObserver implementations. |
LoopbackRestServer |
Extends a
RestServer to be used as loopback device e.g. for testing
purposes such as testing your RestRequestObserver implementations. |
RestCaller |
A
RestCaller describes a REST request and the
RestResponseObserver in charge for handling the response. |
RestCallerBuilder |
An
RestCallerBuilder extends an RestCaller with builder
functionality and adds lambda support for handling the responses
addressed to this RestCaller . |
RestClient |
A client to send requests for communicating with a RESTful server such as the
HttpRestServer . |
RestEndpoint |
An
RestEndpoint subscribes to a RestServer (
HttpRestServer ) and defines the target for a REST request. |
RestEndpointBuilder |
An
RestEndpointBuilder extends an RestEndpoint with builder
functionality and adds lambda support for handling the requests
addressed to this RestEndpoint . |
RestRequest |
A
RestRequest describes a REST request and the RestResponse
providing the response. |
RestRequestBuilder |
An
RestRequestBuilder extends an RestCaller with builder
functionality and adds lambda support for handling the responses
addressed to this RestCaller . |
RestRequestEvent |
Defines a
RestRequestEvent being the request as consumed by a
RestEndpoint . |
RestRequestHandler |
A
RestRequestHandler handles a REST request on the RestClient
instance's side to do the actual technical implementation of sending that
request (or mocking the send-out of a request). |
RestRequestObserver |
The
RestRequestObserver can be coded using the lambda
syntax and processes a request for a given locator and for a given
HttpMethod . |
RestResponse |
Defines a
RestResponse being the base definition of a response as
returned as of a request issued by a RestClient (
HttpRestClient ). |
RestResponseEvent | |
RestResponseObserver |
The
RestResponseObserver can be coded using the lambda
syntax and processes a response from a server. |
RestServer |
The
RestServer acts as the target for clients issuing REST requests. |
Class | Description |
---|---|
AbstractRestClient |
Abstract base implementation of the
RestClient interface being the
foundation for various RestClient implementations such as
HttpRestClientImpl or LoopbackRestClientImpl . |
AbstractRestServer |
Implementation of the base functionality of the
RestServer interface
omitting the HTTP handling part being the foundation for various
RestServer implementations such as HttpRestServerImpl or
LoopbackRestServerImpl . |
HttpRestClientImpl |
The
HttpRestClientImpl implements the HttpRestClient
interface. |
HttpRestClientSingleton |
The singleton of the
HttpRestClientImpl for easy
HttpRestClient access. |
HttpRestClientSugar |
Declarative syntactic sugar which may be statically imported in order to
allow declarative definitions of REST client functionality:
import static org.refcodes.rest.HttpRestClientSugar.*; |
HttpRestServerImpl |
Implementation of the
HttpRestServer interface using the
HttpServer defined in the com.sun.net.httpserver
package. |
HttpRestServerSingleton |
The singleton of the
HttpRestServerImpl for easy
HttpRestServer access. |
HttpRestServerSugar |
Declarative syntactic sugar which may be statically imported in order to
allow declarative definitions of RESTful server functionality:
import static org.refcodes.rest.HttpRestServerSugar. |
LoopbackRestClientImpl |
Implementation if the
LoopbackRestClient for easy testing of your
requests being issued with a RestClient (HttpRestClient ) and
the according response lambda expressions. |
LoopbackRestClientSingleton |
The singleton of the
LoopbackRestClientImpl for easy
LoopbackRestClientImpl access. |
LoopbackRestServerImpl |
Implementation if the
LoopbackRestServer for easy testing of your
requests being received by a RestServer (HttpRestServer ) and
the according response lambda expressions. |
LoopbackRestServerSingleton |
The singleton of the
LoopbackRestServerImpl for easy
RestServer access. |
RestCallerBuilderImpl |
The implementation of the
RestCallerBuilder interface as good old
POJO for use by different RestClient implementations. |
RestEndpointBuilderImpl |
The implementation of the
RestEndpointBuilder interface as good old
POJO for use by different RestServer implementations. |
RestRequestBuilderImpl |
The implementation of the
RestCallerBuilder interface as good old
POJO for use by different RestClient implementations. |
RestRequestEventImpl |
Implementation of the
RestRequestEvent interface as good old POJO for
use by different RestServer implementations. |
RestResponseEventImpl |
Implementation of the
RestResponseEvent interface as good old POJO
for use by different RestClient implementations. |
RestResponseImpl |
Implementation of the
RestResponseEvent interface as good old POJO
for use by different RestClient implementations. |
refcodes-rest
artifact lets you do it the
Bare-Metal
way, or the syntactic sugar
(see
client sugar
or server sugar
) way (meaning the use
of statically imported methods):
Java
based RESTful
server. Below, you see the three steps with the
help of a little syntactic sugar
:
// STEP 1: We use a singleton with syntactic sugar instead of instantiating a HttpRestServer:
import static org.refcodes.rest.HttpRestServerSugar.*;
...
public static void main( String[] args ) {
// STEP 2: Using syntactic sugar, we register our lambda expression:
onGet( "/say/${name}=*", ( aResponse ) -> {
String name = aResponse.getWildcardReplacement( "name" );
aResponse.getHeaderFields().withContentType( MediaType.APPLICATION_JSON ).withAddCookie( "greeting", "Hello " + name + "!" );
return "Hello " + name + "!" ;
} ).open();
// STEP 3: We open the HttpRestServer singleton on port 8080 using our syntactic sugar:
open( 8080 );
}
...
The
TinyRestfulServer demo application uses syntactic sugar
for
setting up a RESTful
server including command line arguments
parsing.
Java
based REST
client. Below you see the three
steps with the help of a little syntactic sugar
:
// STEP 1: We use a singleton with syntactic sugar instead of instantiating a HttpRestClient:
import static org.refcodes.rest.HttpRestClientSugar.*;
...
public static void main( String[] args ) {
// STEP 2: Using syntactic sugar, we define our caller, including the response listener:
doGet( "http://mydomain:8080/say", ( aResponse ) -> {
... = aResponse.getResponse( SomeType.class );
} ).withRequest( ... ).open();
// STEP 3: We opened the caller so it fires the request to port 8080 of domain "mydomain"
}
...
pom.xml
:
<dependencies>
...
<dependency>
<artifactId>refcodes-rest</artifactId>
<groupId>org.refcodes</groupId>
<version>x.y.z</version>
</dependency>
...
</dependencies>
(please refer to Maven Central at
"http://search.maven.org/#search|ga|1|g%3A%22org.refcodes%22" for the most
current version)
If you want the framework to interoperate with SLF4J
(http://www.slf4j.org/) logging, you may instead add the following
dependencies to your pom.xml
:
<dependencies>
...
<dependency>
<artifactId>refcodes-rest</artifactId>
<groupId>org.refcodes</groupId>
<version>x.y.z</version>
</dependency>
<dependency>
<groupId>org.refcodes</groupId>
<artifactId>refcodes-logger-alt-slf4j</artifactId>
<version>x.y.z</version>
</dependency>
...
</dependencies>
(please refer to Maven Central at
"http://search.maven.org/#search|ga|1|g%3A%22org.refcodes%22" for the most
current version)
The artifact is hosted directly at Maven Central (http://search.maven.org). Jump straight to the source codes at Bitbucket (https://bitbucket.org/refcodes/refcodes-rest). Read the artifact's javadoc at javadoc.io (http://www.javadoc.io/doc/org.refcodes/refcodes-rest).
RESTful
service using syntactic sugar
. One drawback of using
syntactic sugar
is that we can only make use of the one
HttpRestServerSingleton
(as of this
syntactic sugar
being the statically imported methods),
preventing us from running multiple HttpRestServer
instances on different ports in one Java
application.
Lets do it the Bare-Metal
way, which is not very complicated
either, and which lets us instantiate as many
HttpRestServer
instances as we want:
...
public static void main( String[] args ) {
// STEP 1: We instantiate our HttpRestServer:
HttpRestServer theRestServer = new HttpRestServerImpl();
// STEP 2: We register our lambda expression:
theRestServer.onGet( "/say/${name}=*", ( aResponse ) -> {
String name = aResponse.getWildcardReplacement( "name" );
aResponse.getHeaderFields().withContentType( MediaType.APPLICATION_JSON ).withAddCookie( "greeting", "Hello " + name + "!" );
return "Hello " + name + "!" ;
} ).open();
// STEP 3: We open the HttpRestServer instance on port 8080:
theRestServer.open( 8080 );
}
...
"/say/${name}=*"
above when
registering your lambda
? Subscribing your lambda
expressions for incoming REST
requests on specific
locators
, you may use a common wildcard
syntax to
define the lambda
's locator pattern
:
*
), the double asterisk (**
)
and the question mark (?
) we refer to as wildcard
:
You get an array with all the substitutes of the wildcards
using
the method RestRequestEvent#getWildcardReplacements()
.
You may name a wildcard
by prefixing it with
"${someWildcardName}=
". For example a named
wildcard
may look as follows: "${arg1}=*
" or
"${arg2}=**
" or "${arg3}=?
" or as of the example
above "/say/${name}=*"
. When your "lambda
" is being
invoked, you can retrieve the wildcard
substitution by the name
of the wildcard
which has been substituted (by parts of the
incoming locator). You can get the text substituting a named
wildcard
using the method
RestRequestEvent#getWildcardReplacement(String)
.
RestServer
: It acts as the target for clients
issuing REST requests. RestEndpointBuilder
)
instances, most easily being created with the
RestServer#subscribeObserver(HttpMethod, String, RestRequestObserver) or the
like methods, are registered as listeners to the
RestServer
. The
RestServer
fires
RestRequestEvent
events to the
RestRequestObserver
s of a
RestEndpoint
dedicated to an according
locator(pattern) for a specific HttpMethod
.
HttpRestServer
: It extends a
RestServer
to be capable of opening a server socket
on the local host with the provided port number via #open(Integer) or with an
additional maximum number of connections via #open(Integer, int) . A
HttpRestServer
can be shutdown via #close().
HttpRestServerImpl
: Implementation of the
HttpRestServer
interface using the HttpServer
defined in the com.sun.net.httpserver artifact. The
HttpRestServer
can also be implemented with other
HTTP servers under the hood, use the
AbstractRestServer
as super class of your own
implementation to easily do so.
RestEndpoint
: A
RestEndpoint
subscribes to a
RestServer
) and defines the target for a REST
request. Therefore the RestEndpoint
describes the
HttpMethod
, the locator (pattern) to which to
respond as well as a RestRequestObserver
responsible for processing the request. The
RestRequestObserver
is invoked as soon as a request
with the given HttpMethod
for a locator matching the
given Locator-Pattern is being processed by the
RestServer
).
RestEndpointBuilder
): A
RestEndpointBuilder
) extends a
RestEndpoint
with builder functionality and adds
lambda support for handling the request addressed to this
RestEndpoint
. The lambda defined as
RestRequestObserver
acts as the single listener to
this RestEndpoint
responsible for handling the
request for which this RestEndpoint
is responsible.
RestRequestObserver
: It can be coded using the
lambda syntax and processes a request on a given locator for a given
HttpMethod
. The
RestRequestObserver
is working with a context (the
RestRequestEvent
).
HttpRestServerSugar
: The syntactic sugar for
setting up your RESTful service as quickly as possible ("import static
org.refcodes.rest.HttpRestServerSugar.*;").
REST
client
using syntactic sugar
. One drawback of using
syntactic sugar
is that we can only make use of the one
HttpRestClientSingleton
(as of this
syntactic sugar
being the statically imported methods),
preventing us from running multiple HttpRestClient
instances in one Java
application (which is actually no real
drawback, as the HttpRestClientSingleton
can fire
at any HTTP or HTTPS targets you wish to connect to).
Lets do it the Bare-Metal
way, which is not very complicated
either, and which lets us instantiate as many
HttpRestClient
instances as we want:
...
public static void main( String[] args ) {
// STEP 1: We instantiate our HttpRestClient:
HttpRestClient theRestClient = new HttpRestClientImpl();
// STEP 2: We register our lambda expression:
theRestClient.doRequest( HttpMethod.POST, "http://mydomain:8080/say", ( aResponse ) -> {
String theResponse = aResponse.getResponse( String.class );
} ).withRequest( ... ).open();
// STEP 3: We opened the caller so it fires the request to port 8080 of domain "mydomain"
}
...
RestClient
: It acts as the origin for clients
issuing REST requests. RestCallerBuilder
instances,
most easily being created with the RestClient#doRequest( HttpMethod ,
aLocator, aResponseObserver ) or the like methods, are registered as
listeners to the RestClient
's request, waiting for
the response. The RestClient
fires
RestResponseEvent
events to the
RestResponseObserver
of the
RestCaller
dedicated to the according request.
HttpRestClient
: It extends a
RestClient
to be capable of doing HTTP (HTTPS). A
HttpRestClient
can be shutdown via #close().
HttpRestClientImpl
: Implementation of the
HttpRestClient
interface using the
HttpURLConnection
(https://docs.oracle.com/javase/8/docs/api/java/net/HttpURLConnection.html)
defined in the java.net package. The HttpRestClient
can also be implemented with other HTTP connectors under the hood, use the
AbstractRestClient
as super class of your own
implementation to easily do so.
RestCaller
: A
RestCaller
subscribes to a
RestClient
(
HttpRestClient
)'s request and defines the target
for a REST request's response. Therefore the
RestCaller
describes the
RestResponseObserver
responsible for processing the
request's response. The RestResponseObserver
is
invoked as soon as a response for the according request is being received by
the RestClient
(
HttpRestClient
).
RestCallerBuilder
: A
RestCallerBuilder
extends a
RestCaller
with builder functionality and adds
lambda support for handling the responses addressed to this
RestCaller
. The lambda defined as RequestObserver
acts as the single listener to this RestCaller
responsible for handling the response for which this
RestCaller
is responsible.
RestResponseObserver
: It can be coded using the
lambda syntax and processes a request's response. The
RestResponseObserver
is working with a context (the
RestResponseEvent
).
HttpRestClientSugar
: The syntactic sugar for
setting up your REST client as quickly as possible ("import static
org.refcodes.rest.HttpRestClientSugar.*;").
Copyright © 2017. All rights reserved.