README
“The
REFCODES.ORG
codes represent a group of artifacts consolidating parts of my work in the past years. Several topics are covered which I consider useful for you, programmers, developers and software engineers.”
What is this repository for?
With this artifact you easily create your serverless
RESTful services and REST clients. It lets you do it the Bare-Metal
way or the syntactic sugar
(see HttpRestClientSugar
or HttpRestServerSugar
) way (being the use of statically imported methods).
Quick start archetype
Use the refcodes-archetype-alt-rest
archetype to create a bare metal REST
driven Java
application within just one source code file:
Please adjust
my.corp
with your actual Group-ID andmyapp
with your actual Artifact-ID!
mvn archetype:generate \
-DarchetypeGroupId=org.refcodes \
-DarchetypeArtifactId=refcodes-archetype-alt-rest \
-DarchetypeVersion=3.0.4 \
-DgroupId=my.corp \
-DartifactId=myapp \
-Dversion=1.0-SNAPSHOT
Using the defaults, this will generate a RESTful
server and client application by harnessing the refcodes-rest
toolkit.
How do I get set up?
To get up and running, include the following dependency (without the three dots “…”) in your pom.xml
:
1
2
3
4
5
6
7
8
9
<dependencies>
...
<dependency>
<artifactId>refcodes-rest</artifactId>
<groupId>org.refcodes</groupId>
<version>3.0.4</version>
</dependency>
...
</dependencies>
The artifact is hosted directly at Maven Central. Jump straight to the source codes at Bitbucket. Read the artifact’s javadoc at javadoc.io.
RESTful server
Within three simple steps you implement your lightweight Java
based RESTful
server. Below, you see the three steps with the help of a little syntactic sugar
:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 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}=*", ( aRequest, aResponse ) -> {
String name = aRequest.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
expression for the response - 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
:
1
2
3
4
5
6
7
8
9
10
11
// 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 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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
...
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}=*", ( aRequest, aResponse ) -> {
String name = aRequest.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)
.
As of refcodes-rest
version 1.1.3
a placeholder “${arg1}” with no wildcard assignment “=” is equivalent to “${arg1}=*”. In the example above you could have used "/say/${name}"
instead of "/say/${name}=*"
.
Error handling
In case an Exception
gets thrown while your lambda
is processing an HTTP-Response
due to an incoming HTTP-Request
, you may either handle it manually in your lambda
expression or you may use a predefined behavior or you may even register a custom global Exception
handler. The predefined behavior is configured as follows:
1
2
3
...
HttpRestServer theRestServer = new HttpRestServerImpl().withHttpExceptionHandling( HttpExceptionHandling.REPLACE );
...
The behavior is specified by the enumeration HttpExceptionHandling
. You currently have the following options on how an exceptional situation is handled:
HttpExceptionHandling.REPLACE
: Create a newHTTP-Response
with the accordingHTTP-Status-Code
and the error description fields.HttpExceptionHandling.UPDATE
: Keep the so far processedHTTP-Response
as is except theHTTP-Status-Code
and also update all error description fields. Useful when you want to preserve already set fields.HttpExceptionHandling.MERGE
: Keep the so far processedHTTP-Response
as is except update the actualHTTP-Status-Code
, add only non-existing fields if possible with the error description fields. Useful when you manually prepared theHTTP-Response
yourself.HttpExceptionHandling.KEEP
: Do not modify the so far processedHTTP-Response
except update the actualHTTP-Status-Code
. Useful when you manually prepared theHTTP-Response
yourself.HttpExceptionHandling.EMPTY
: Create a newHTTP-Response
with the accordingHTTP-Status-Code
and and an empty body.
In case the Media-Type
used is Application/JSON
, then the error description fields generated by the predefined exception handler looks as follows:
1
2
3
4
5
6
7
8
9
{
"status": {
"exception": "org.refcodes.net.NotFoundException",
"code": "404",
"alias": "NOT FOUND",
"message": "There is none endpoint for handling resource locator </repl/sessionsx> with HTTP-Method <GET>.",
"timestamp": "1525436619219"
}
}
This custom global exception handler is represented by an instance of the functional interface HttpExceptionHandler
being registered to your HttpRestServer
. You may register it using the lambda
notation:
1
2
3
4
5
6
7
...
HttpRestServer theRestServer = new HttpRestServerImpl().withOnHttpException( ( request, response, exception, statusCode ) -> {
// ...
response.setResponse( new HttpBodyMapImpl().withPut( "message", exception.getMessage() ) );
// ...
} );
...
The RESTful server’s bits and pieces
-
RestServer
: It acts as the target for clients issuingREST
requests.RestEndpointBuilder
instances, most easily being created with theRestServer#subscribeObserver(HttpMethod, String, RestRequestObserver)
or the like methods, are registered as listeners to theRestServer
. TheRestServer
firesRestRequestEvent
events to theRestRequestObserver
s of aRestEndpoint
dedicated to an accordinglocator
(pattern) for a specificHttpMethod
. -
HttpRestServer
: It extends aRestServer
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)
. AHttpRestServer
can be shutdown via#close()
. -
HttpRestServerImpl
: Implementation of theHttpRestServer
interface using theHttpServer
defined in thecom.sun.net.httpserver
artifact. TheHttpRestServer
can also be implemented with other HTTP servers under the hood, use theAbstractRestServer
as super class of your own implementation to easily do so. -
RestEndpoint
: ARestEndpoint
subscribes to aRestServer
(HttpRestServer
) and defines the target for aREST
request. Therefore theRestEndpoint
describes theHttpMethod
, the locator (pattern) to which to respond as well as aRestRequestObserver
responsible for processing the request. TheRestRequestObserver
is invoked as soon as a request with the givenHttpMethod
for a locator matching the given Locator-Pattern is being processed by theRestServer
(HttpRestServer
). -
RestEndpointBuilder
: ARestEndpointBuilder
extends aRestEndpoint
with builder functionality and addslambda
support for handling the request addressed to thisRestEndpoint
. The lambda defined asRestRequestObserver
acts as the single listener to thisRestEndpoint
responsible for handling the request for which thisRestEndpoint
is responsible. -
HttpRestServerSugar
: The syntactic sugar for setting up yourRESTful
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:
1
2
3
4
5
6
7
8
9
10
11
...
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 issuingREST
requests.RestCallerBuilder
instances, most easily being created with theRestClient#doRequest( HttpMethod , aLocator, aResponseObserver )
or the like methods, are registered as listeners to theRestClient
’s request, waiting for the response. TheRestClient
firesRestResponseEvent
events to theRestResponseObserver
of theRestCaller
dedicated to the according request. -
HttpRestClient
: It extends aRestClient
to be capable of doing HTTP (HTTPS). AHttpRestClient
can be shutdown via#close()
. -
HttpRestClientImpl
: Implementation of theHttpRestClient
interface using theHttpURLConnection
defined in thejava.net
package. TheHttpRestClient
can also be implemented with other HTTP connectors under the hood, use theAbstractRestClient
as super class of your own implementation to easily do so. -
HttpRestClientSugar
: The syntactic sugar for setting up yourREST
client as quickly as possible (import static org.refcodes.rest.HttpRestClientSugar.*;
).
Examples
Please refer to the example source code for more examples on the usage of this artifact.
See also the blog post Bare-Metal REST with just a few lines of codes!
Eureka support
The refcodes-rest-ext-eureka
artifact supports the Eureka microservice registry/discovery mechanism (providing a sidecar) to register (attach) your RESTful services to Eureka.
See the
refcodes-rest-ext-eureka
artifact’s example source code on how to enable your RESTful services to use Eureka service discovery.
Useful information may be puzzled together from resources such as Eureka REST operations, JSON format to register service with Eureka or the eureka-client.properties
file.
Contribution guidelines
- Writing tests
- Code review
- Adding functionality
- Fixing bugs
Who do I talk to?
- Siegfried Steiner (steiner@refcodes.org)
Terms and conditions
The REFCODES.ORG
group of artifacts is published under some open source licenses; covered by the refcodes-licensing
(org.refcodes
group) artifact - evident in each artifact in question as of the pom.xml
dependency included in such artifact.