JAXB 2.2.10

see also http://docs.oracle.com/javaee/5/tutorial/doc/bnbbf.html
see also https://jaxb.java.net/tutorial/index.html
see also https://jaxb.java.net/guide/index.html - Unofficial JAXB Guide
see also How to get simple and better typed binding in https://metro.java.net/guide/ch03.html

fixed attributes will be generated as a java constant.
<xs:attribute name="country" type="xs:NMTOKEN" fixed="US"/>
@XmlSchemaType(name = "NMTOKEN")
public final static String COUNTRY = "US";
Specifies the base type used for collections.
<xs:element name="item" minOccurs="1" maxOccurs="unbounded">
@XmlElement(required = true)
protected List<Items.Item> item = new Vector<Items.Item>();
typesafeEnumBase = a list of QNames, each of which must resolve to a simple type definition
Specifies that all simple type definitions deriving directly or indirectly from e.g. xsd:string and having enumeration facets should be bound by default to a typesafe enum.
<xs:simpleType name="USState">
	<xs:restriction base="xs:string">
		<xs:enumeration value="AK"/>
		<xs:enumeration value="AL"/>
		<xs:enumeration value="AR"/>
		<xs:enumeration value="CA"/>
		<xs:enumeration value="MA"/>
		<!-- and so on ... -->
The default value is false. choiceContentProperty is not relevant when the bindingStyle is elementBinding (see below).
<xs:complexType name="fileUploadRequest">
		<xs:element name="path" type="xs:string"/>
		<xs:element name="file" type="xs:base64Binary"/>
Xjc with choiceContentProperty="false":
public class FileUploadRequest {
    protected String path;
    protected byte[] file;
Xjc with choiceContentProperty="true":
    @XmlElement(name = "path", type = String.class),
    @XmlElement(name = "file", type = byte[].class)
protected Object pathOrFile;
typesafeEnumMemberName = "generateName" | "generateError"
generateError specifies that the code generator generates an error when it cannot map an enumeration to a Java enum type.
<xs:simpleType name="USState">
	<xs:restriction base="xs:string">
		<xs:enumeration value="CA"/>
		<xs:enumeration value="MA"/>
		<xs:enumeration value="1MA"/> -> 1MA is an invalid java name
		<!-- and so on ... -->
[ERROR] Cannot generate a constant name from the enumeration value "1MA". Use <jaxb:typesafeEnumMember name="..."/> to specify one.
generateName specifies that member names will be generated following the pattern VALUE_N. N starts off at one, and is incremented for each member of the enumeration.
    private final String value;
Type constraint checking is performed when setting a property.
item.setQuantity( new BigInteger( "-5" ) );// must be a positive number here
If @enableFailFastCheck was "true" and the optional FailFast validation method was supported by an implementation, a TypeConstraintException would be thrown here. Note that the JAXB implementation does not support the FailFast feature.

First see FileUploadRequest schema declaration above.
Causes two additional property methods, isSetPath and isSetFile, to be generated. These methods enable a client application to distinguish between schema default values and values occurring explicitly within an instance document. Some good folks claim unsetPath and unsetFile should be generated too but it didn't happened for me (with or without a default attribute set on path element).

Consider this element:
<xs:element name="sOmE_PROPerty" type="xs:string"/>
Jxc generation result when asWordSeparator (default value):
@XmlElement(name = "sOmE_PROPerty")     -> it's an invisible underscore between sOmE and PROPerty
protected String sOmEPROPerty;
Jxc generation result when asCharInWord:
protected String sOmE_PROPerty;         -> it's an invisible underscore between sOmE and PROPerty

XSD schema

<!-- example -->
  <xs:restriction base="xs:string">
    <xs:enumeration value="Audi"/>
    <xs:enumeration value="Golf"/>
    <xs:enumeration value="BMW"/>

<!-- example -->
<xs:complexType name="personinfo">
    <xs:element name="firstname" type="xs:string"/>
    <xs:element name="lastname" type="xs:string"/>

<xs:complexType name="fullpersoninfo">
    <xs:extension base="personinfo">
        <xs:element name="address" type="xs:string"/>
        <xs:element name="city" type="xs:string"/>
        <xs:element name="country" type="xs:string"/>

<!-- example -->
<element name="callMyApp" type="dc:processingHook" />
http://www.xml.com/pub/a/2001/08/22/easyschema.html -> best article
That leaves us with <complexType> with <complexContent>, which ensures that there will not be any data content in the element.
<complexType name="processingHook">
    <restriction base="xs:anyType"> -> the default syntax for complex types is complex content that restricts anyType

<complexType name="processingHook"></complexType>

<!-- example -->
<product prodid="1345" />

<xs:element name="product">
      <xs:restriction base="xs:anyType">
        <xs:attribute name="prodid" type="xs:positiveInteger"/>

<xs:complexType name="prodtype">
  <xs:attribute name="prodid" type="xs:positiveInteger"/>

<!-- example -->
Apparently, you can't restrict simpleContent within a complexType, only extend it.
<shoesize country="france">35</shoesize>
<xs:complexType name="shoetype">
    <xs:extension base="xs:integer">
      <xs:attribute name="country" type="xs:string" />

<!-- example -->
<xs:element name="marks">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="100"/>

Spring Data REST

The core functionality of Spring Data REST is to export resources for Spring Data repositories.
Spring Data REST exposes sub-resources of every item resource for each of the associations the item resource has. By default, Spring Data REST uses HAL (hypertext application language) to render responses.

RepositoryRestMvcConfiguration - the @Configuration for Spring Data REST
RepositoryRestConfigurerAdapter - used to customize the configuration

By default, Spring Data REST serves up REST resources at the root URI, "/". Register a @Bean which extends RepositoryRestConfigurerAdapter and overwrite configureRepositoryRestConfiguration in order to change it. With spring boot use spring.data.rest.basePath=/new-base-path-for-spring-data-rest in application.properties.
http://ip:port/base-path-for-spring-data-rest returns a JSON with the first level of resources provided with Spring Data REST.

@RepositoryRestResource - used on a Repository interface to customize the path and name of the resource
@RestResource - used on a method to customize the path and name of the exported resource; use exported = false in order not to export the resource

Annotation org.springframework.data.rest.core.config.Projection used to define altered views for entities (e.g.: not showing the password for user).
URI would look like: http://localhost:8080/persons/1?projection=noPassword
@Projection can be used with SpEL expression to create new properties.
An excerpt is a projection that is applied to a resource collection automatically, e.g.:
@RepositoryRestResource(excerptProjection = NoPassword.class)
interface PersonRepository extends CrudRepository {}

Validation is achived using a registered org.springframework.validation.Validator instance:
a. beforeCreatePersonValidator -> prefix the bean name with the Data REST event name
b. assigning Validators manually -> override RepositoryRestMvcConfiguration.configureValidatingRepositoryEventListener and add the validators

Events: BeforeCreateEvent, AfterCreateEvent, BeforeSaveEvent, AfterSaveEvent, BeforeLinkSaveEvent, AfterLinkSaveEvent, BeforeDeleteEvent, AfterDeleteEvent. Writing an ApplicationListener:
a. extend AbstractRepositoryEventListener (onBeforeSave, etc) -> makes no distinction based on the type of the entity
b. write an annotated handler -> @RepositoryEventHandler on class and @HandleBeforeSave on method (first parameter determines the domain type whose events you’re interested)

Creating links from Spring MVC controllers to Spring Data REST resources is possible with injectable RepositoryEntityLinks (equivalent to EntityLinks from Spring HATEOAS): entityLinks.linkToCollectionResource(Person.class).

ALPS (Application-Level Profile Semantics) is a data format for defining simple descriptions of application-level semantics.
ALPS (application/alps+json or application/schema+json) -> used for metadata provided by a Spring Data REST-based application.
http://ip:port/base-path-for-spring-data-rest/profile -> metadata location
ALPS list first entity's attributes (+ projections) then operations.

Spring security works fine with Spring Data REST; just use @PreAuthorize as usual.

The developer of the HAL spec has a useful application: the HAL Browser.

Write a custom handler (overriding Spring Data REST response handlers) for a specific resource using @RepositoryRestController (instead of @RestController). There's a custom HandlerMapping instance that responds only to the RepositoryRestController which is considered before the one for @Controller or @RestController.

Use ResourceProcessor interface in order to provide links to other resources from a particular entity. You declare spring beans implementing ResourceProcessor for a specific entity.
If you register your own ConversionService in the ApplicationContext and register your own Converter, then you can return a Resource implementation of your choosing.

Maven dependency


HATEOAS means Hypermedia As The Engine Of Application State

ResourceSupport - support class for building DTOs with links

ControllerLinkBuilder - allows to create links by pointing to controller classes (Spring MVC controllers or JAX-RS resource classes)
With ControllerLinkBuilder you depend on controller classes in order to create links.

@EnableEntityLinks - inspects Spring MVC controllers and JAX-RS resource for @ExposesResourceFor(model class) and allows injecting of EntityLinks
With EnableEntityLinks you depend on model/business classes in order to create links; I think it's better instead of ControllerLinkBuilder.