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 #open(Integer) 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 |
---|---|
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.*; |
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. |
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):
RESTful
server
lambda
expressions
RESTful
server
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.
REST client
- Instantiate the
REST
client
- Register your
lambda
expressions
- Fire the client's
REST
request
Again, within three simple steps you implement your lightweight
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"
}
...
How do I get set up?
To get up and running, include the following dependency (without the three
dots "...") in your pom.xml
:
<dependencies>
...
<dependency>
<artifactId>refcodes-rest</artifactId>
<groupId>org.refcodes</groupId>
<version>1.1.1</version>
</dependency>
...
</dependencies>
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>1.1.1</version>
</dependency>
<dependency>
<groupId>org.refcodes</groupId>
<artifactId>refcodes-logger-alt-slf4j</artifactId>
<version>1.1.1</version>
</dependency>
...
</dependencies>
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).
How do I get started with the RESTful server?
Above you saw an example on how to setup your own 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 );
}
...
The Locator-Pattern
Did you notice the Locator-Pattern "/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:
- A single asterisk (
*) matches zero or more characters within a locator
name.
- A double asterisk (
**) matches zero or more characters across directory
levels.
- A question mark (
?) matches exactly one character within a locator
name.
The single asterisk (*), 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)
.
The RESTful server's bits and pieces
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.*;).
How do I get started with the REST client?
Above you saw an example on how to setup your own 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"
}
...
The REST client's bits and pieces
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.*;
).
Examples
Please refer to the example code at
"https://bitbucket.org/refcodes/refcodes-rest/src/master/src/test/java/org/refcodes/rest/impls".
org/refcodes/rest/impls/
Copyright © 2017. All rights reserved.