io.neba.api.resourcemodels.ResourceModelCache 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.resourcemodels;

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

/**
 * Function of the resource model cache
 * Implementations cache the result of {@link Resource#adaptTo(Class) resource adaptations} to a specific target type.
 * They are invoked by the generic NEBA adapter factory prior to the lookup and mapping of
 * a {@link io.neba.api.annotations.ResourceModel}. If the model is not contained
 * in any cache, it is obtained from its spring bean factory, mapped and afterwards 
 * {@link #put(Resource, Object, Object) added} to all known {@link ResourceModelCache resource model caches}.
 * 
 * Providing a cache implementation
 * To provide a cache implementation, publish an OSGi service with this interface.
 * It will automatically be detected by NEBA. You may provide any number of caches. NEBA
 * will always attempt to retrieve a cached model from all of them. The first cache 
 * {@link #get(Object) providing} a non-null model wins.
 * There is no guarantee concerning the order in which caches are invoked.

 * Likewise, a model will be {@link #put(Resource, Object, Object) stored} in all available caches.
 * 
 * Default implementations shipped with NEBA
 * NEBA comes with a sensible default implementation of this cache, the request-scoped resource model cache,
 * which is configurable via the Apache Felix console.

 * 
 * Architecture considerations when providing a custom cache implementation
 * Caching is hard. You must be aware that correctly scoping, i.e. expiring objects
 * from this cache is crucial for both system stability and semantic correctness. Specifically,
 * items in the cache must never ever:
 * 
 * 
 *   Live longer than the resources they represent, including any subsequent resources mapped to
 *       the resource model
 *   Live longer than the {@link io.neba.api.annotations.ResourceModel resource model}
 *       represented by the model type and any subsequent resource models mapped to it
 *  
 * 
 * @author Olaf Otto
 */
public interface ResourceModelCache {
	/**
	 * Retrieve a cached model.
	 * 
	 * @param key The key used to identify the stored model. Never null.
	 * @return The cached model, or null.
	 */
	 T get(Object key);
	
	/**
	 * @param resource The resource {@link Resource#adaptTo(Class) adapted} to the target type. Never null.
	 * @param model the model representing the mapped result of the adaptation. Can be null.
     * @param key the key by which the model is identified and {@link #get(Object) retrieved}. Never null.
	 */
	 void put(Resource resource, T model, Object key);
}