io.neba.api.annotations.ResourceModel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of io.neba.neba-api Show documentation
Contains all annotations, tag libraries and lifecycle callback interfaces of NEBA. All packages of this API bundle are exported. Change to the API that are not byte code compatible only occur in major revisions.
There is a newer version: 5.2.3
Show newest version
/*
  Copyright 2013 the original author or authors.
  
  Licensed under the Apache License, Version 2.0 the "License";
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
  

  http://www.apache.org/licenses/LICENSE-2.0
  

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 */

package io.neba.api.annotations;


import org.apache.sling.api.resource.Resource;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * A resource model represents sling {@link org.apache.sling.api.resource.Resource resources} with
 * specific sling resource types, JCR primary node types or mixin types.
 *
 * 
Registering resource models
 * Classes annotated with @{@link ResourceModel} are automatically detected by NEBA when their containing packages
 * are specified in the Neba-packages bundle manifest header, e.g.
 *
 *  * <Neba-Packages>
 * com.acme.app.models,
 * com.acme.app.more.models
 * </Neba-Packages>
 * 
 *
 * 
 * When using NEBA with Spring, models can be declared as Spring beans. In this case, NEBA will automatically detect all beans
 * annotated with {@link ResourceModel} in the application context. Spring beans representing resource models must be prototypically scoped as they represent
 * dynamically created, contextual pieces of data, not singletons.
 * 
 *
 * Obtaining model instances
 * Resources with suitable types can be {@link org.apache.sling.api.resource.Resource#adaptTo(Class) adapted to}
 * the corresponding models. This adaptation can be done automatically using /apps/neba/neba.js with HTL, {@link io.neba.api.tags.DefineObjectsTag}
 * with JSP or the {@link io.neba.api.services.ResourceModelResolver} service.
 *
 * Mapping resource properties to models
 * The fields of a @{@link ResourceModel} are automatically mapped from the properties
 * of the {@link org.apache.sling.api.resource.Resource resource} it represents,
 * unless they are static, final, injected (annotated with @Inject, @Autowired or @Resource) or
 * annotated with @{@link Unmapped}. See also @{@link Path}, @{@link This}
 * and @{@link Reference} and refer to the NEBA user guide.
 *
 * Examples
 *
 *  *    // A resource model for a sling resource type.
 *    @{@link ResourceModel}(types = "shared/components/teaser")
 *    public class MyTeaser {
 *       ...
 *    }
 *
 *    // A resource model for a JCR node type.
 *    @{@link ResourceModel}(types = "nt:base")
 *    public class MyBaseModel {
 *       ...
 *    }
 *
 *    // A resource model for a JCR mixin node type.
 *    @{@link ResourceModel}(types = "mix:versionable")
 *    public class MyVersionableModel {
 *       ...
 *    }
 * 
 *
 * 
 * A {@link ResourceModel} applies to the type hierarchy of a resource.
 * Therefore, if a {@link org.apache.sling.api.resource.Resource} has no
 * specific {@link ResourceModel}, i.e. no mapping to its
 * {@link org.apache.sling.api.resource.Resource#getResourceType()} or node
 * type, its resource hierarchy, followed by its node type hierarchy (including mixin types) are
 * searched for a less specific model.
 * 
 *
 * @author Olaf Otto
 * @see org.apache.sling.api.resource.Resource#adaptTo(Class)
 * @since 1.0.0
 */
@Target({TYPE, ANNOTATION_TYPE})
@Retention(RUNTIME)
@Documented
public @interface ResourceModel {
    /**
     * A {@link org.apache.sling.api.resource.Resource#getResourceType()
     * resource type} or JCR node type (including mixin types) are acceptable
     * values for the type mapping. Example: "myapps/components/mycomponent",
     * "nt:base", "mix:versionable".
     */
    String[] value();

    /**
     * @deprecated use {@link #value()} instead. This method will be removed in future versions of neba.
     */
    @Deprecated
    String[] types() default {};

    /**
     * A user-defined name for the model. Views can lookup a model by name (see neba.js and {@link io.neba.api.services.ResourceModelResolver#resolveMostSpecificModelWithName(Resource, String)}),
     * thus, decoupling a view from the models type. If not given, the model name is automatically derived from the model's type name.
     */
    String name() default "";
}