CuriTemplate (edison-hal 2.1.0 API)

java.lang.Object
- de.otto.edison.hal.CuriTemplate

```
public class CuriTemplate
extends java.lang.Object
```
A utility class used to handle user-defined link-relation types and CURI templates.

A CURI is a templated Link with link-relation type curies, a name and a href containing a single placeholder {rel}:
```
     {
         "_links": {
             "curies: [
                  {"name": "x", "href": "http://example.com/rels/{rel}", "templated": true}
             ]
         }
     }
 
```
or:
```
     Link curi = Link.curi("x", "http://example.com/rels/{rel}");
 
```
You can construct a CuriTemplate from a curi like this:
```
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);
 
```
A Link-relation type (rel) specifies the semantics of a Link. A next link, for example, points to the next resource (page) in a sequence of paged resources. While rels like self, next or prev are predefined types, you may define user-defined link-relation types as well. If you need to use a user-defined rel like, for example a rel used to refer to a user resource, you should use URIs like http://example.org/rels/product.

Because user-defined link-relation types (or custom rels) are quite verbose, CURIES can be used to abbreviate them. The following example shows how this will look like in HAL+JSON:
```
     {
         "_links": {
             "curies: [
                  {"name": "x", "href": "http://example.com/rels/{rel}", "templated": true}
             ],
             "x:product": [
                  {"href": "http://example.com/products/42"},
                  {"href": "http://example.com/products/43"},
                  {"href": "http://example.com/products/44"},
                  {"href": "http://example.com/products/45"}
             ],
             "x:shoppingCart": {"href": "http://example.com/shoppingCart/4711"}
         }
     }
 
```
Sometimes it is necessary to construct CURIED rels from a expanded rel, or vice versa. The CuriTemplate can be used to do things like this.
Since:

2.0.0

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`curiedRelFrom(java.lang.String rel)` Returns the `rel` in CURIED format.
`static CuriTemplate`	`curiTemplateFor(Link curi)` Creates a CuriTemplate from a CURI Link.
`java.lang.String`	`expandedRelFrom(java.lang.String rel)` Returns the `rel` in expanded format.
`Link`	`getCuri()` Returns the curi `Link` of this template.
`boolean`	`isMatching(java.lang.String rel)` Returns true, if the given link-relation type is matching the CuriTemplate pattern, false if not.
`boolean`	`isMatchingCuriedRel(java.lang.String rel)` Returns true, if the given link-relation type is a CURI rel matching the CuriTemplate pattern, false if not.
`boolean`	`isMatchingExpandedRel(java.lang.String rel)` Returns true, if the given link-relation type is a non-CURI rel matching the CuriTemplate pattern, false if not.
`static java.util.Optional<CuriTemplate>`	`matchingCuriTemplateFor(java.util.List<Link> curies, java.lang.String rel)` Returns an optional CuriTemplate that is `matching` the rel parameter, or empty if no matching CURI is found.
`java.lang.String`	`relPlaceHolderFrom(java.lang.String rel)` Returns the placeholder from a link-relation type that is matching the `CuriTemplate`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

curiTemplateFor

public static CuriTemplate curiTemplateFor(Link curi)

Creates a CuriTemplate from a CURI Link.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

Parameters:: curi - a CURI Link
Returns:: CuriTemplate
Throws:: java.lang.IllegalArgumentException - if the parameter is not a valid CURI.
Since:: 2.0.0

matchingCuriTemplateFor
```
public static java.util.Optional<CuriTemplate> matchingCuriTemplateFor(java.util.List<Link> curies,
                                                                       java.lang.String rel)
```
Returns an optional CuriTemplate that is matching the rel parameter, or empty if no matching CURI is found.
Example:
```
     List<Link> curies = asList(
          Link.curi("x", "http://example.org/rels/{rel}"),
          Link.curi("y", "http://example.com/link-relations/{rel}")
     );
     String rel = "y:example";
     CuriTemplate template = CuriTemplate.matchingCuriTemplateFor(curies, rel);
 
```
The returned UriTemplate is created from the second CURI, as only this is matching the curied rel parameter y:example. Because of this, template.expandedRelFrom(rel) will return http://example.com/link-relations/example
Parameters:

curies - a List of curies Links

rel - the link-relation type to check against the curies

Returns:

optional CuriTemplate

Throws:

java.lang.IllegalArgumentException - if the curies parameter contains non-CURI links.

Since:

2.0.0

isMatching

public boolean isMatching(java.lang.String rel)

Returns true, if the given link-relation type is matching the CuriTemplate pattern, false if not.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

     // Returns true:
     template.isMatching("http://example.org/rels/product");
     template.isMatching("x:product"):

     // Returns false:
     template.isMatching("http://example.com/link-relations/product");
     template.isMatching("y:product");

Parameters:: rel - a link-relation type.
Returns:: boolean
Since:: 2.0.0

isMatchingCuriedRel

public boolean isMatchingCuriedRel(java.lang.String rel)

Returns true, if the given link-relation type is a CURI rel matching the CuriTemplate pattern, false if not.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

     // Returns true:
     template.isMatchingCuriedRel("x:product"):

     // Returns false:
     template.isMatchingCuriedRel("http://example.org/rels/product");
     template.isMatchingCuriedRel("http://example.com/link-relations/product");
     template.isMatchingCuriedRel("y:product");

Parameters:: rel - a link-relation type.
Returns:: boolean
Since:: 2.0.0

isMatchingExpandedRel

public boolean isMatchingExpandedRel(java.lang.String rel)

Returns true, if the given link-relation type is a non-CURI rel matching the CuriTemplate pattern, false if not.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

     // Returns true:
     template.isMatchingExpandedRel("http://example.org/rels/product");

     // Returns false:
     template.isMatchingExpandedRel("x:product"):
     template.isMatchingExpandedRel("http://example.com/link-relations/product");
     template.isMatchingExpandedRel("y:product");

Parameters:: rel - a link-relation type.
Returns:: boolean
Since:: 2.0.0

relPlaceHolderFrom

public java.lang.String relPlaceHolderFrom(java.lang.String rel)

Returns the placeholder from a link-relation type that is matching the CuriTemplate.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

     // Returns "product":
     template.relPlaceHolderFrom("http://example.org/rels/product");
     template.relPlaceHolderFrom("x:product"):

     // Throws IllegalArgumentException:
     template.relPlaceHolderFrom("http://example.com/link-relations/product");
     template.relPlaceHolderFrom("y:product");

Parameters:: rel - a link-relation type.
Returns:: boolean
Throws:: java.lang.IllegalArgumentException - if the rel parameter does not match the CuriTemplate.
Since:: 2.0.0

curiedRelFrom

public java.lang.String curiedRelFrom(java.lang.String rel)

Returns the rel in CURIED format.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

     // Returns "x:product":
     template.curiedRelFrom("http://example.org/rels/product");
     template.curiedRelFrom("x:product"):

     // Throws IllegalArgumentException:
     template.curiedRelFrom("http://example.com/link-relations/product");
     template.curiedRelFrom("y:product");

Parameters:: rel - a link-relation type.
Returns:: boolean
Throws:: java.lang.IllegalArgumentException - if the rel parameter does not match the CuriTemplate.
Since:: 2.0.0

expandedRelFrom

public java.lang.String expandedRelFrom(java.lang.String rel)

Returns the rel in expanded format.

Example:


     Link curi = Link.curi("x", "http://example.org/rels/{rel}");
     CuriTemplate template = CuriTemplate.curiTemplateFor(curi);

     // Returns "http://example.org/rels/product":
     template.curiedRelFrom("http://example.org/rels/product");
     template.curiedRelFrom("x:product"):

     // Throws IllegalArgumentException:
     template.curiedRelFrom("http://example.com/link-relations/product");
     template.curiedRelFrom("y:product");

Parameters:: rel - a link-relation type.
Returns:: boolean
Throws:: java.lang.IllegalArgumentException - if the rel parameter does not match the CuriTemplate.
Since:: 2.0.0

getCuri
```
public Link getCuri()
```
Returns the curi Link of this template.

Returns:

curi

Since:

2.0.0

Class CuriTemplate

Method Summary

Methods inherited from class java.lang.Object

Method Detail

curiTemplateFor

matchingCuriTemplateFor

isMatching

isMatchingCuriedRel

isMatchingExpandedRel

relPlaceHolderFrom

curiedRelFrom

expandedRelFrom

getCuri