Configuring Resources with YogaEntityConfigurations

The Yoga framework supports a construct called YogaEntityConfigurations. For each resource (e.g. User) in your REST API, you have the option of defining a corresponding YogaEntityConfiguration. The entity configuration allows gives you to precisely configure what resource data will be available to consumers of your API, and it allows you keep that configuration logic separated from your model.

1. Creating a YogaEntityConfiguration

You create a YogaEntityConfiguration by extending the YogaEntityConfiguration<T> abstract class, which is typed to your resource. Here is a sample YogaEntityConfiguration implementation for the User class:

public class UserFieldPopulator extends YogaEntityConfiguration<User>
{
    @Override
    public List<String> getCoreFields()
    {
        return Arrays.asList( "id", "name" );
    }

    @Override
    public List<String> getSelectableFields()
    {
        return Arrays.asList( "id", "name", "favoriteArtists" );
    }

    @Override
    public String getURITemplate()
    {
        return "/user/{id}";
    }
}

The getCoreFields method allows you to enumerate which fields of the resource are Core fields, as described in the Tutorial section. Naming a field in this method has the exact same effect as using the @Core annotation on the corresponding getter method in the model object. This method may return an empty list to specify no core fields.

The getSelectableFields method allows you to restrict which properties of your model object will be available for query in a selector expression. If a client specifies a field in a selector expression that is not a supported field, it will be ignored when Yoga renders the response. This method may return null to specify that all readable properties of the model object are supported fields.

The getURITemplate method allows you to specify the format of the hypertext link to a specific instance of the REST resource. Note that you can use the brackets { and } to wrap wildcard expressions that correspond to readable properties of the model object. So in this example, we have a URI Template of /user/{id}. If the Yoga framework renders a URI for a User object with an id of 5, the URI will be /user/5. This method may return null to indicate that Yoga wil not render a URI for this resource.

2. Registering Your YogaEntityConfiguration

Once you define your YogaEntityConfiguration, you will need to register it to make it available to the Yoga framework. Here is the configuration to add it to the EntityConfigurationRegistry, which is injected into Yoga's ResultTraverser.

<bean id="resultTraverser" class="org.skyscreamer.yoga.mapper.ResultTraverser"
      p:entityConfigurationRegistry-ref="entityConfigurationRegistry" p:classFinderStrategy-ref="hibernateClassFinder"/>

<bean id="entityConfigurationRegistry" class="org.skyscreamer.yoga.configuration.DefaultEntityConfigurationRegistry">
    <constructor-arg>
        <list>
            <bean class="org.skyscreamer.yoga.demo.dto.UserFieldPopulator"/>
        </list>
    </constructor-arg>
</bean>

Now, any requests for resources of the type User will be subject to the settings defined in your entity configuration.

3. Using FieldPopulatorSupport

Extend the provided abstract class YogaEntityConfiguration. This class provides default implementations of the interface methods. The default implementations define no core fields, allow all readable properties to be supported, and define no URI Template.

Here is a usage of the support class:

public class UserEntityConfiguration extends YogaEntityConfiguration<User>
{
    public List<String> getCoreFields()
    {
        return Arrays.asList( "id", "name" );
    }
}

Here, we explicitly define the core fields on the User object, but we accept the default implementations of getSupportedFields and getURITemplate.