<commit_before>**Build Status** [![Build Status](https://buildhive.cloudbees.com/job/RestExpress/job/HyperExpress/badge/icon)](https://buildhive.cloudbees.com/job/RestExpress/job/HyperExpress/)

**Waffle.io** [![Stories in Ready](https://badge.waffle.io/RestExpress/HyperExpress.png?label=ready)](https://waffle.io/RestExpress/HyperExpress)

[(Video) Introduction to HyperExpress](http://www.youtube.com/watch?v=TQqc7goKVsM&list=UUzaZL1VLtdVTiZ8k07z65jg&feature=share)

HyperExpress
============

Offers a simple way to add hypermedia links to your domain models or DTOs before serializing them to clients. It also
contains classes to help support "link expansion" in your services by using callbacks to enrich the newly created
'Resource' instances before they get serialized.
 
HyperExpress supports several ways to generate links in responses.  If you want to create Link instances
or URLs (using token substitution in URLs patterns) by hand using the Builder pattern (Location header anyone?):

* **HyperExpress** = a Singleton entry-point for HyperExpress functionality.
* **LinkBuilder** = Create Link instance using the builder pattern, optionally using URL token substitution.
* **UrlBuilder** = Create a string URL from a URL pattern, substituting URL tokens to produce a fully-populated URL.

Additionally, HyperExpress now supports the concept of a Resource, which is a generalized interface that
creates a 'presentation model' where your links can be added, other resources can be embedded, etc. with
output rendering being abstracted and dependent on the requested content type.

There are three concepts that play together to accomplish this:

* **RelationshipDefinition** = Use this to describe relationships between resources and namespaces.
* **TokenResolver** = For relationships (in the RelationshipBuilder) that have templated URLs, this class is able to populate the URL parameters, substituting actual values for the tokens (e.g. '{userId}').
* **TokenBinder** = For a collection of resources, resolves tokens in a URL by binding properties from individual objects in the collection to identifiers in the URL.

Additionally, there are a couple of helper classes:

* **MapStringFormat** = which will substitute names in a string with provided values (such as an URL).
* **RelTypes** = contains constants for REST-related standard Iana.org link-relation types.

The HyperExpress-Core project is primarily abstract implementations. Specific functionality is in the sub-projects, such
as HyperExpress-HAL, which has HAL-specific rendering (and parsing) of Resource implementations.

Please see HyperExpress-HAL for usage information: https://github.com/RestExpress/HyperExpress/tree/master/hal

Interested in other functionality?  Drop me a line... let's talk!

How-To
======

There are three phases in which HyperExpress helps you out managing links in your resources;

* Configuring HyperExpress for Media Types
* Defining Static Relationships (between resources)
* Resolving URL tokens (a token in a URL is replaced with an ID)
* Creating Resources using a Factory

After that, it's the 'simple' matter of serializing the Resource to JSON (or XMl, or whatever).
HyperExpress-HAL has a serializer and deserializer for Jackson. Assuming you have your
own Jackson configuration, simply plug these in to your module (see the HyperExpress-HAL README).

Configuring HyperExpress
========================

Maven resources:

Stable:

```xml
<dependency>
    <groupId>com.strategicgains</groupId>
    <artifactId>HyperExpress-HAL</artifactId>
    <version>2.2</version>
</dependency>
```

Development snapshot:

```xml
<dependency>
    <groupId>com.strategicgains</groupId>
    <artifactId>HyperExpress-HAL</artifactId>
    <version>2.3-SNAPSHOT</version>
</dependency>
```
Or you can download the jar file directly from http://search.maven.org/#search%7Cga%7C1%7Chyperexpress

Note that if you want to use the SNAPSHOT version, the snapshot repository must be configured in your settings.xml file as follows:

```xml
  <profiles>
    <profile>
       <id>allow-snapshots</id>
          <activation><activeByDefault>true</activeByDefault></activation>
       <repositories>
         <repository>
           <id>snapshots-repo</id>
           <url>https://oss.sonatype.org/content/repositories/snapshots</url>
           <releases><enabled>false</enabled></releases>
           <snapshots><enabled>true</enabled></snapshots>
         </repository>
       </repositories>
     </profile>
  </profiles>
```
Next, add resource factories to HyperExpress so HyperExpress knows which factory to use depending on the MediaType of the request.
In order for createResource() and createCollectionResource() to know what type of resource to create based on content-type,
ResourceFactoryStrategy instances must be registered for each media type support.
<commit_msg>Updated README for latest version.<commit_after>**Build Status** [![Build Status](https://buildhive.cloudbees.com/job/RestExpress/job/HyperExpress/badge/icon)](https://buildhive.cloudbees.com/job/RestExpress/job/HyperExpress/)

**Waffle.io** [![Stories in Ready](https://badge.waffle.io/RestExpress/HyperExpress.png?label=ready)](https://waffle.io/RestExpress/HyperExpress)

[(Video) Introduction to HyperExpress](http://www.youtube.com/watch?v=TQqc7goKVsM&list=UUzaZL1VLtdVTiZ8k07z65jg&feature=share)

HyperExpress
============

Offers a simple way to add hypermedia links to your domain models or DTOs before serializing them to clients. It also
contains classes to help support "link expansion" in your services by using callbacks to enrich the newly created
'Resource' instances before they get serialized.
 
HyperExpress supports several ways to generate links in responses.  If you want to create Link instances
or URLs (using token substitution in URLs patterns) by hand using the Builder pattern (Location header anyone?):

* **HyperExpress** = a Singleton entry-point for HyperExpress functionality.
* **LinkBuilder** = Create Link instance using the builder pattern, optionally using URL token substitution.
* **UrlBuilder** = Create a string URL from a URL pattern, substituting URL tokens to produce a fully-populated URL.

Additionally, HyperExpress now supports the concept of a Resource, which is a generalized interface that
creates a 'presentation model' where your links can be added, other resources can be embedded, etc. with
output rendering being abstracted and dependent on the requested content type.

There are three concepts that play together to accomplish this:

* **RelationshipDefinition** = Use this to describe relationships between resources and namespaces.
* **TokenResolver** = For relationships (in the RelationshipBuilder) that have templated URLs, this class is able to populate the URL parameters, substituting actual values for the tokens (e.g. '{userId}').
* **TokenBinder** = For a collection of resources, resolves tokens in a URL by binding properties from individual objects in the collection to identifiers in the URL.

Additionally, there are a couple of helper classes:

* **MapStringFormat** = which will substitute names in a string with provided values (such as an URL).
* **RelTypes** = contains constants for REST-related standard Iana.org link-relation types.

The HyperExpress-Core project is primarily abstract implementations. Specific functionality is in the sub-projects, such
as HyperExpress-HAL, which has HAL-specific rendering (and parsing) of Resource implementations.

Please see HyperExpress-HAL for usage information: https://github.com/RestExpress/HyperExpress/tree/master/hal

Interested in other functionality?  Drop me a line... let's talk!

How-To
======

There are three phases in which HyperExpress helps you out managing links in your resources;

* Configuring HyperExpress for Media Types
* Defining Static Relationships (between resources)
* Resolving URL tokens (a token in a URL is replaced with an ID)
* Creating Resources using a Factory

After that, it's the 'simple' matter of serializing the Resource to JSON (or XMl, or whatever).
HyperExpress-HAL has a serializer and deserializer for Jackson. Assuming you have your
own Jackson configuration, simply plug these in to your module (see the HyperExpress-HAL README).

Configuring HyperExpress
========================

Maven resources:

Stable:

```xml
<dependency>
    <groupId>com.strategicgains</groupId>
    <artifactId>HyperExpress-HAL</artifactId>
    <version>2.3</version>
</dependency>
```

Development snapshot:

```xml
<dependency>
    <groupId>com.strategicgains</groupId>
    <artifactId>HyperExpress-HAL</artifactId>
    <version>2.4-SNAPSHOT</version>
</dependency>
```
Or you can download the jar file directly from http://search.maven.org/#search%7Cga%7C1%7Chyperexpress

Note that if you want to use the SNAPSHOT version, the snapshot repository must be configured in your settings.xml file as follows:

```xml
  <profiles>
    <profile>
       <id>allow-snapshots</id>
          <activation><activeByDefault>true</activeByDefault></activation>
       <repositories>
         <repository>
           <id>snapshots-repo</id>
           <url>https://oss.sonatype.org/content/repositories/snapshots</url>
           <releases><enabled>false</enabled></releases>
           <snapshots><enabled>true</enabled></snapshots>
         </repository>
       </repositories>
     </profile>
  </profiles>
```
Next, add resource factories to HyperExpress so HyperExpress knows which factory to use depending on the MediaType of the request.
In order for createResource() and createCollectionResource() to know what type of resource to create based on content-type,
ResourceFactoryStrategy instances must be registered for each media type support.

{'fraction_non_alphanumeric': 0.09158035073325813, 'fraction_numerical': 0.0030766075274330836, 'mean_word_length': 4.8676293622142, 'pattern_counts': {'":': 0, '<': 87, '<?xml version=': 0, '>': 87, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6356971', 'n_tokens_mistral': 2654, 'n_tokens_neox': 2463, 'n_words': 1036}