Documentation

NEBA is a lightweight, high-performance and open source Content-to-Object mapping extension for Apache Sling and Adobe AEM™. With NEBA's minimal set of well-documented annotations, engineers can easily use repository content of arbitrary complexity to build building well maintainable, high performance solutions in AEM™ and Apache Sling.
In addition, NEBA provides an optional integration of Spring and Spring MVC - the de-facto standard for java enterprise applications - and its enormous ecosystem of read--to-use solutions.

NEBA models are Java POJO's with a simple annotation, allowing type-safe representation of repository data. Performance-critical features, such as lazy loading and tooling to monitor model behavior are provided out-of-the-box.

NEBA strives for simplicity and furthers readable and changeable code. It does so by adhering to the principals of Separation of Concerns and providing sensible defaults. For instance, NEBA does not mix Dependency Injection with content mapping or handling HTTP requests and maps content to fields by default - just like mature persistence standards like the Java Persistence API (JPA).

How is NEBA different from Sling Models?

NEBA and Sling models are are no contradiction and can be used alongside without any issue. Sling Models and NEBA models can even be injected into one another.

• NEBA always associates its models with sling resource types or JCR node types to facilitate type safety.
• NEBA has been developed for high-performance and features request-scoped caching and lazy-loading out of the box.
• NEBA ships with comprehensive tooling to support developers and administrators.
• NEBA provides extensible semantic annotations for almost all possible use cases to maximise convenience and minimize code.
• NEBA ships an optional integration with Spring and Spring MVC, thus allowing to use the de facto standard for Java Enterprise Applications to be used with Sling and AEM™.

Get started with NEBA with two simple steps:

Step 1: Download and install NEBA

Install the delivery package and add a dependency to the NEBA API to your project.

Step 2: Add the Neba-Packages header to your bundle(s)

Add a comma-separated list of packages containing your NEBA models to your bundle, e.g. using maven:

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <configuration>
        <instructions>
            <Neba-Packages>
                my.project.models
            </Neba-Packages>
        </instructions>
    </configuration>
</plugin>

That's it - you may now proceed to Write resource models. You can use the sample project as a starting point

The NEBA sample project

The NEBA sample project demonstrates both the Neba-Packages based core functionality and using the Neba Spring integration.

What is a resource model?

A Resource model is a type safe representation of a Sling resource, written as a Java class. The data of a resource can be mapped to the resource model, similar to an ORM mapping the data of a relational DB to an entity class. In addition, resource models can be injected with collaborators, e.g. OSGi services. Resource model instances are obtained by adapting a resource to the type or super type of the resource model. A resource model and the Sling resource types it represents are defined using the @ResourceModel annotation.

Resource models are useful for explicitly modelling complex resource relationship semantics and functionality belonging to specific resource types and the data of the corresponding resources.

Resource models are not useful for simply exposing the properties of the current resource in a view - here, using Sling's generic ${properties} or ${resource} representation is recommended.

Resources, resource types and resource models

Let's assume we need a simple JAVA model for a sling component called "carousel". The carousel has the sling:resourceType "foundation/components/carousel". The component has the following properties:

{
  "jcr:primaryType": "nt:unstructured",
  "playSpeed": "6000",
  "jcr:lastModifiedBy": "admin",
  "pages": [
    "/content/geometrixx/en/events/techsummit",
    "/content/geometrixx/en/events/userconf"
  ],
  "jcr:lastModified": "Tue Oct 05 2010 14:14:27 GMT+0200",
  "transTime": "1000",
  "sling:resourceType": "foundation/components/carousel",
  "listFrom": "static"
}

Create the following class in your bundle package (i.e. within or below the "my.project.models" package)

@ResourceModel("foundation/components/carousel")
public class Carousel {
}

The resource type given in the @ResourceModel annotation does not have to be the exact resource type of the resource. One may also specify any resource super type of the resource, primary node type or mixin type. for example, the resource super type of the carousel could be "foundation/components/list". Using this resource type in a @ResourceModel would work, too. This way, one can provide general models for super types, and more specific models for derived types, e.g. a generic model for pages and a more specific model for specific page types.

Once a bundle with NEBA models is active, all of its models appear in the NEBA model registry (/system/console/modelregistry) in the sling console. If they are not visible in the model registry, the bundle either failed to start or is missing the "Neba-Packages" header.

@ResourceModel("my/resource/type")
public class SomeModelClass {
    @Inject
    @Filter("(zone=eu)")
    private DataSource dataSource;
}

@ResourceModel("my/resource/type")
public class SomeModelClass {
    public SomeModelClass(@Inject @Filter("(zone=eu)") DataSource ds) {
        this.dataSource = ds;
    }
}

@ResourceModel("my/resource/type")
public class SomeModelClass {
    @Inject
    private Optional<OtherService> otherService;

    public SomeModelClass(@Inject @Filter("(zone=eu)") Optional<DataSource> ds) {
        this.dataSource = ds;
    }
}

@ResourceModel("my/resource/type")
public class SomeModelClass {
    @Inject
    @Filter("(some=filter)")
    private List<OtherService> otherServices;

    public SomeModelClass(@Inject List<DataSource> dataSources) {
        this.dataSources = dataSources;
    }
}

Using models in views

Resource models can be used in either HTL (Sightly) or JSP views by adapting the resource to the desired model, like so:

<sly data-sly-use.m="my.package.MyModel"> ...</sly>

<sling:adaptTo adaptable="${resource}" adaptTo="my.package.MyModel" var="m" />

Mapping properties and resources to models

NEBA automatically maps the properties of a Resource to fields named like the properties, unless the field is annotated with @Unmapped, @Inject, is static or final. Additional semantics, such as mapping referenced resource, children or specific paths are supported by a an extensible set of annotations. Following, we will map the properties of the following resource:

{
  "jcr:primaryType": "nt:unstructured",
  "playSpeed": "6000",
  "jcr:lastModifiedBy": "admin",
  "pages": [
    "/content/geometrixx/en/events/techsummit",
    "/content/geometrixx/en/events/userconf"
  ],
  "jcr:lastModified": "Tue Oct 05 2010 14:14:27 GMT+0200",
  "transTime": "1000",
  "sling:resourceType": "foundation/components/carousel",
  "listFrom": "static"
}

Let's select "pages", "playSpeed", "transTime" and add them to the model:

@ResourceModel("foundation/components/carousel")
public class Carousel {
    private String playSpeed;
    private String transTime;
    private List<String> pages;

    public String getPlaySpeed() {
        return playSpeed;
    }
    public String getTransTime() {
        return transTime;
    }
    public List<Resource> getPages() {
        return pages;
    }
}

The properties of the model may then be rendered like so:

Play speed: ${m.playSpeed}
Trans time: ${m.transTime}
Pages: ${m.pages}

This will create the following output:

Play speed: 6000
Trans time: 1000
Pages: ["/content/geometrixx/en/events/techsummit", ...]

Annotations for resource to model mapping

By default, NEBA will map all fields of a model from the properties or child resources of the adapted resource, unless the fields are static, final, annotated with @Unmapped, @Inject or @Autowired. The following annotations are thus only needed if a simple property-to-field mapping is not enough.

Resolving references with the @Reference annotation

In the above example, "pages" is an array of strings and not the actual resources the "pages" property is referring to. If you want to resolve and / or adapt the referenced resources, NEBA provides the @Reference annotation to declare that a field contains one ore more references to other Resources:

@Reference
private List<Resource> pages;

When NEBA detects a @Reference annotation, it assumes that the value of the corresponding property is one or more resource paths. It obtains the corresponding resources and provides them as a Collection (or a single resource, if the annotated field is not a collection type). However, you are not limited to using "Resource" for your reference. The following also works, provided there is a "Page" model the referenced resources can be adapted to:

@Reference
private List<Page> pages;

Here, NEBA loads the resource referenced in the "pages" property, adapts each resource to "Page" and returns a collection containing the resulting non-null Page instances.

@Reference(append = "/jcr:content")
@Path("pages")
private List<PageContent> pageContents;

Here, instead of resolving and adapting the paths in the property "pages" directly, "/jcr:content" is appended to all of the paths prior to resolution. Note also the use of the @Path annotation to define the property name.

Resolving children with the @Children annotation

While the resource hierarchy is conveniently navigable using the generic Resource model (i.e. using getChildren()), one often has to subsequently adapt the children. Consequently, the children are adapted in a loop, including a null check for each adaptation result. Here, NEBA offers another powerful annotation: @Children. This annotation can be used on a Collection, Set or List-typed field (similar to the @Reference-annotation). Then, NEBA injects the children of either the current resource (if no other annotation is present), or of the resource defined by the @Reference or @Path of the field:

@Children
private List<Resource> children;

Of course, NEBA will also automatically adapt the children to the generic type of the list - for instance, you could write:

@Children
private List<Page> childPages;

@Children can be combined with both @Reference and @Path to fetch the children of a referenced resource or a resource designated by a specific path, i.e. the following works as well:

@Path("/content/site")
@Children
// Contains the children of /content/site
private List<Page> countryPages;

@Reference
@Path("link")
@Children
// Contains the children of resource referenced in the resource property "link"
private List<Page> linkChildren;

@Reference
@Children
// Also contains the children of resource referenced in the resource property "link"
private List<Page> link;

Furthermore, one may specify a relative path to be resolved below every child using the property "resolveBelowEveryChild". For example, one could obtain all resources named "jcr:content" underneath all children of the current resource, like so:

@Children(resolveBelowEveryChild = "jcr:content")
private List<PageContent> childPageContents;

Using the @Path annotation to specify property names or resource paths

Lets assume a property called "jcr:lastModified" shall be mapped to a model.

private Date lastModified;

This will not yet work - NEBA maps the properties by name, in this case the name contains characters ("jcr:") unsuitable for a field name. In such cases, use the @Path annotation to specify the property from which the field's value shall be obtained:

@Path("jcr:lastModified")
private Date lastModified;

@Path is not limited to property names, but allows specifying absolute and relative paths:

@Path("/content/geometrixx/en")
private Resource en;

@Path("..")
private Resource parent;

Furthermore, one can use placeholders in the @Path to dynamically provide path elements:

@Path("/content/geometrixx/${language}")
private Resource homepage;

To resolve the ${language} placeholder, provide an OSGi service implementing the PlaceholderVariableResolver interface. Such services will be asked to resolve the value for a placeholder key, i.e. "language" in the above example. The first service to resolve a nun-null value for the placeholder will win. A hardcoded example:

public class MyVariableResolver implements PlaceholderVariableResolver {
    public String resolve(String variableName) {
        if ("language".equals(variableName)) {
            return "en";
        }
        return null;
    }
}

The @This annotation

Fields annotated with @This are injected with the current resource, or anything the resource is adaptable to. This annotation is thus not just useful for accessing the underlying Resource but has significant architectural value. Using @This, one may split up a model into multiple aspects and compose them dynamically, like so:

@ResourceModel(...)
public class MyModel {
    @This
    // OtherModel models a different aspect of the same resource.
    private OtherModel resource;
}

One can also use the @This annotation to obtain the Resource that is mapped onto the model:

@This
private Resource resource;

Models for crosscutting concerns

A @ResourceModel is not restricted to sling:resourceType's - one can also map it to the JCR primary node type or any of the mixin types of a Node. For example, let's assume that there is a requirement to implement a custom access protection of arbitrary content. In addition, a content manager may configure access restriction to any content (e.g. pages or a binary assets). In this case, neither the resource types nor the content paths to which the protection applies are known in advance. Here, using a mixin node type could help. A mixin can be assigned to any node at any time anywhere in the content hierarchy. It can define additional properties that can be set on the node, such as a set of properties defining how an access restriction is configured. Let us assume a protected content is assigned the mixin "mix:AccessRestricted". One may then create a model for any access restricted content like so:

@ResourceModel("mix:AccessRestricted")
public class AccessRestricted {
 ....
}

Finally, one can adapt to this model (e.g., in a view or filter) to determine whether the corresponding resource has restricted access, and what the restrictions are.

You can either use the existing nodes types in AEM and Sling or add your own, e.g. by creating and deploying CND (JCR node type definition) files. There is even an IntelliJ IDEA plugin for CND files offering some syntax support. You may also want to read up on the Jackrabbit Oak documentation of JCR node types and the JCR repository spec.

Lazy loading

Reading data into an object graph - such as NEBA models - bears the risk of loading more data than required for rendering. Especially when there is a significant amount of repository content, being able to load models on demand rather then up front is crucial for building high-performance implementations. To achieve this, NEBA enables lazy-loading model relationships.

Lazy loading collections of references

All collection-typed references are automatically provided as lazy-loading proxies, for example @Children and @Reference collections:

@ResourceModel("...")
public class MyModel {
  @Children
  private List<Page> children; // Provided as a lazy-loading proxy
  @Reference
  private Collection<Page> pages; // Provided as a lazy-loading proxy as well
}

The contents of these collections are loaded as soon as a collection method - such as get, size, isEmpty, iterator - is called. The lazy-loading behavior for collections is thus completely transparent.

Declaring lazy-loading relationships using the Lazy<T> interface

1:1 relationships are not automatically lazy. In order to make them lazy-loading, NEBA provides the Lazy interface:

@ResourceModel("...")
public class MyModel {
  @Reference
  private Lazy<Page> page;
  @Path("/content/path")
  private Lazy<Resource> otherResource;
}

@ResourceModel("...")
public class MyModel {
  @Reference
  private Resource r;

  public void doSomething() {
      if (r != null) {
         // work with r
      }
  }
}

The Lazy<T> interface provides all features of the JAVA 8 "Optional" type. NEBA automatically provides an implementation that will load the reference upon request. Of course, you may also use the interface for collection-typed references:

@ResourceModel("...")
public class MyModel {
  @Children
  private Lazy<Collection<Page>> children;
  @Reference
  private Lazy<Collection<Page>> pages;
}

In this case, NEBA will not provide the collection as a lazy-loading proxy, but simply load it when requested via the Lazy interface implementation.

Rendering NEBA models as JSON

Since 5.1.0, NEBA features an out of the box JSON rendering servlet. This servlet can be configured to respond to certain selectors and resource types and will adapt the request's resource to a specified or the most specific NEBA model and render a JSON view. To enable the JSON rendering, head to the system console's configuration tab and add a configuration to the NEBA model JSON view servlet.

Here, you can configure an arbitrary amount of JSON view renderers. For each configuration, a dedicated servlet instance will be published hence allowing for dedicated configurations in a multi-tenant scenario. Each JSON view servlet can be configured wth its own selectors and Jackson features. In addition, The servlet supports HTTP Etag generation based on the resource and customized Cache-Control headers.

After a JSON view configuration is added, a resource's model can be rendered as JSON using the URL schema

</resource/path>.<one of the configured selectors>[.<optional specific model name>].json
// E.g. /content/site/en_US/contact.neba.json

An example for configuring and using NEBA JSON views can be found in the NEBA sample project.

Performing additional initializations

Sometimes it is necessary to perform additional initializations after all collaborators of a @ResourceModel are injected and all resource properties have been mapped to the model. Here, using the @AfterMapping annotation is recommended, as it guarantees that model construction, dependency injection and content-to-model mapping have completed regardless of the model source, e.g. Neba-Packages or a spring application context). When using Spring, @PostConstruct will always be invoked prior to content-to-object mapping due to bean life cycle restrictions by spring.

@ResourceModel("my/model/type")
public class MyModel {
   @This
   private Resource resource;
   @AfterMapping
   public void initializeSomething() {
        // resource is initialized at this point.
        this.resource.adaptTo...
   }
}

Application-level caching

NEBA's central and most performance critical feature is the adaptation of resource models. There, resource and model resolution, content-to-model mapping and data type conversion occurs. This core functionality features a safe and sensible integrated cache, the request-scoped resource model cache. This cache can be disabled via the Felix console (configuration tab). For further information, consult the Javadoc of the ResourceModelCache.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context
                           http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/mvc
                           http://www.springframework.org/schema/mvc/spring-mvc.xsd">

    <!-- Automatically discover spring beans below this package namespace.
        It is best-practice that this namespace is exclusive for the bundle to avoid conflicts with imported packages. -->
    <context:component-scan base-package="my.bundle.namespace"/>

    <!-- Setup the annotation-driven MVC infrastructure  -->
    <mvc:annotation-driven/>
</beans>

package my.bundle.namespace;

import org.springframework.stereotype.Component;
import io.neba.api-annotations.ResourceModel;
import org.springframework.context.annotation.Scope;

@Scope("prototype")
@Component
@ResourceModel("my/resource/type")
public class MyModel {
    ...
}

When a resource is adapted to the respective model (or a super class or interface of the model), a model instance is obtained from the respective application context's bean factory. Subsequently, the resource data is mapped to the model via field injection and the resulting model is returned as the .adaptTo call result.

While NEBA provides a default MVC infrastructure similar to the defaults provided by Spring's DispatcherServlet, it is recommended to explicitly configure MVC support in the blueprint context using <mvc:annotation-driven />. This also enables advanced features, such as automated conversion of controller responses to JSON.

<?xml version="1.0" encoding="UTF-8"?>
<beans
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       ...
       xsi:schemaLocation="
        http://www.springframework.org/schema/mvc
        http://www.springframework.org/schema/mvc/spring-mvc.xsd
        ...">

    <mvc:annotation-driven />
</beans>

Let's create a simple Controller called "DemoController". We will use Spring's @Controller annotation; other styles (such as mapping by bean names etc.) are also supported. The purpose of this controller is to echo a parameter that we provide in a way that could be cached by AEM's Dispatcher cache.

@Controller
public class DemoController {
}

A @Controller is automatically detected and registered (as a singleton) by Spring's classpath scanning. Let's use Spring's REST support to both define the URL the controller listens to and the parameter we expect:

@Controller
public class DemoController {
    @RequestMapping("/echo/{param}")
    @ResponseBody
    public String echo(@PathVariable("param") String paramToEcho) {
       return paramToEcho;
    }
}

That's it. You may now call your controller e.g. with /bin/mvc.do/echo/HelloWorld.txt.

Furthermore, NEBA automatically provides handler method argument resolvers for Sling-specific request elements, SlingHttpServletRequest and -Response, RequestPathInfo and ResourceResolver, like so:

@Controller
public class DemoController {
    @RequestMapping("/echoTitle")
    @ResponseBody
    public String echo(ResourceResolver resolver, RequestPathInfo info) {
       ...
    }

    @RequestMapping("/echoTitle")
    @ResponseBody
    public String echo(SlingHttpServletRequest request) {
        ...
    }
}

It is thus not necessary to obtain these elements from the request.

Note that the annotation-driven controllers have a lot more very powerful options. See the Spring MVC documentation for more examples. NEBA also supports Spring's special view names for redirecting and forwarding views: returning "redirect:/some/path" from a controller method will cause a redirect to /some/path, returning forward:/some/path will forward the request to /some/path, see also MVC redirecting.

You may also directly work with the response. For this, provide your own View in the ModelAndView provided by the controller; this way, your View's render method is used to render the response. Alternatively, you may also simply write to the response and either let the controller method return "null" or make it void. This is however bad practice and thus discouraged.

@Controller
public class DemoController {
    @RequestMapping("/myMethod")
    public String echo(@ResourceParam Page page) {
       // do something
       return "myApp/controllerViews/myView"
    }
}

${page}

${properties.page}

@Controller
public class DemoController {
    @RequestMapping("/echoTitle")
    @ResponseBody
    public String echo(@ResourceParam Page page) {
       return page.getTitle();
    }
}

@Controller
public class DemoController {
    @RequestMapping("/echoTitle")
    @ResponseBody
    public String echo(@ResourceParam(defaultValue = "/default/resource/path") Page page) {
       return page.getTitle();
    }
}

@Controller
public class DemoController {
    @RequestMapping("/echoTitle")
    @ResponseBody
    public String echo(@ResourceParam(append = "/jcr:content") PageContent pageContent) {
       return pageContent.getTitle();
    }
}

@Component
@Scope(WebApplicationContext.SCOPE_REQUEST)
public class MyType {
  ...
}

To support developers beyond writing resource models, NEBA ships with a set of useful development and administration tools for exploring resource model characteristics as well as quickly resolving the resource model / content relationships. Finally, a log viewer integrated into the Felix console greatly improves issue analysis in cases where serial access to the system is an issue.

NEBA model registry

The model registry allows viewing all currently registered resource models, their source bundle and the resource types they are mapping to. In addition, the models can be filtered to find models mapping to specific content or models compatible to specific classes.

NEBA model statistics

For every detected resource model, NEBA extracts metadata that is reused to efficiently map resources to these models. Whenever resources are mapped to models, NEBA gathers data regarding the mapping duration. This combined resource model data is available via a JSON REST API in the model statistics console (/system/console/modelstatistics/api/statistics).

The NEBA model statistics console (/system/console/modelstatistics) uses this data to visualize the corresponding model characteristics. In addition, the console allows querying the data to display models with certain features, for instance to discover models performing below average and/or excessively loading data from the repository.

This unique feature makes visible what could usually only be discovered through time-consuming analysis using a profiling tool. Furthermore, the model statistics allow real-time performance monitoring and analysis on any system. This is especially valuable for productive systems - there, content changes may trigger performance degradation and attaching a profiler usually isn't an option. NEBA's model statistics console makes finding performance bottleneck's in resource models fast and easy - further adding to better performing implementations.

The log viewer

Developers do not always have serial access to a system in order to analyse log files - however, being able to investigate the log files of a Sling instance is often key to finding and resolving issues timely. Here, NEBA provides the log viewer Felix console plugin - a safe way to view analyse and obtain the configured log files of a Sling instance for authenticated users of the Felix console.

The log viewer automatically detects errors in the current log file excerpt of an error.log and allows tailing logfiles in real-time. It also allows downloading logfiles as ZIP compressed packages for offline analysis.

NEBA is extensible via a set of service interfaces provided in the Service Provider Interface (SPI) API package.

Implementing custom annotations

With NEBA, you can easily add your own annotations to provide additional features. Fields annotated with a custom annotation are handled by the corresponding OSGi service implementing the AnnotatedFieldMapper interface. Implementations may map any non-transient annotated field, including fields directly or indirectly (meta-annotations) annotated with any of NEBA's standard annotations. Thus, AnnotatedFieldMappers can not only be used to support custom annotations, but are allowed to augment NEBA's standard annotation-based mapping behavior.

Here is an example for an annotation and a custom processor that translates a field's string value using a locale obtained from the resource path.

@Retention(RUNTIME)
public @interface Translate {
}


@Component(service = AnnotatedFieldMapper.class)
public class TranslateAnnotationMapper implements AnnotatedFieldMapper<String, Translate> {
    // E.g. /content/site/en_US/...
    private static final Pattern LANGUAGE_IN_PATH = compile("/content/(?<site>[^/]+)/(?<locale>[A-z]{2}(_[A-z]{2})?)/.*");

    @Reference
    @Filter("(component.name=org.apache.sling.i18n.impl.JcrResourceBundleProvider)")
    private ResourceBundleProvider resourceBundleProvider;

    @Nonnull
    @Override
    public Class<? super String> getFieldType() {
        return String.class;
    }

    @Nonnull
    @Override
    public Class<Translate> getAnnotationType() {
        return Translate.class;
    }

    @CheckForNull
    @Override
    public String map(OngoingMapping<String, Translate> ongoingMapping) {
        String value = ongoingMapping.getResolvedValue();
        if (isEmpty(value)) {
            return value;
        }
        return resourceBundleProvider.getResourceBundle(getLocale(ongoingMapping.getResource())).getString(value);
    }

    private Locale getLocale(Resource resource) {
        return LocaleUtils.toLocale(LANGUAGE_IN_PATH.matcher(resource.getPath()).group("locale"));
    }
}
    

This annotation could then be used in your model like so:

@ResourceModel("project/components/cta")
public class CallToAction {
  @Translate
  private String buttonText;
}

Lifecycle callbacks

After creation and dependency injection, a resource model is injected with the properties of the resource which is adapted to the model. For programmatic extensibility, the NEBA API contains the lifecycle callback interface ResourceModelPostProcessor. Providing an OSGi service with this interface allows customizing and even overriding a ResourceModel after the resource properties are mapped to it.

Providing custom resource model factories

NEBA automatically registers models provided by ResourceModelFactory OSGi services. Thus, resource model factories can be provided by publishing a ResourceModelFactory OSGI service. NEBA core, for instance, publishes such a factory for resource models declared using the Neba-Packages header.

Custom AOP support

AOP sometimes involves wrapping java objects in proxies or otherwise enhancing their type. If resource models are enhanced in this fashion before NEBA maps resource data or injects collaborators, NEBA may no longer be able to do so since the required fields or bean properties are no longer accessible. Here, one can publish an AopSupport service. This service is asked to prepare a (potentially AOP-enhanced) model instance for injection. For instance, this service may return the underlying target of an AOP proxy instance, or the original object if it is not enhanced. NEBA's spring integration module, for instance, publishes an AopSupport service for CGlib proxies.

The following documentation is not meant to be complete in a sense of covering every implementation detail. It strives to illustrate the core design ideas, as well as the most important components and processes of NEBA.

Bundles

NEBA's main functionality is delivered by two bundles, API and core. The API exclusively contains annotations, interfaces and tag libraries and has no dependency to the core bundle. It is designed to rarely change and to be the exclusive interface between code using NEBA and the NEBA implementation, thus completely separating application code from NEBA's implementation concerns.

In addition, NEBA provides a Spring integration bundle. This bundle enables using Spring Beans as Models for Resources and Spring MVC within Apache Sling. The Spring integration is exclusively based on Gemini Blueprint, the Open Source Reference Implementation of the OSGi Blueprint specification.

Resource model detection

Similar to Sling models, the NEBA core registers classes annotated with @ResourceModel in the packages contained in the Neba-Packages header of a bundle. Subsequently, the bundle containing the models is augmented with a Resource Model Factory Service representing the models. This service implementation is also responsible for providing instances of the models and performing basic instantiation services, such as dependency injection and invoking life cycle callbacks.

The NEBA Spring support post-processes the Blueprint application context of a bundle, looking for Spring Beans annotated with @ResourceModel. In addition, the Spring support enables request-scoped Spring beans and Spring MVC in Sling.

Resource model registration and adaptation

The registration of resource models and the subsequent management of the resource model metadata for mapping purposes account for the most valuable NEBA features. Here, the NEBA core collects all ResourceModelFactory services and registers all models provided by them. Subsequently, NEBA core publishes a Sling Adapter Factory allowing the adaptation from resources with the suitable type(s) to the respective models. The mapping of resources and their properties to the resource models is done by NEBA core during such an adaptation.

Please use the below form to see the upgrade path from one version of NEBA to another.