/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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 org.apache.wicket.request.resource;
import java.util.Locale;
import java.util.Queue;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentLinkedQueue;
import org.apache.wicket.request.resource.ResourceReference.Key;
import org.apache.wicket.util.lang.Args;
import org.apache.wicket.util.lang.Generics;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Allows to register and lookup {@link ResourceReference}s per Application.
*
* @see org.apache.wicket.Application#getResourceReferenceRegistry()
* @see org.apache.wicket.Application#newResourceReferenceRegistry()
*
* @author Matej Knopp
* @author Juergen Donnerstag
*/
public class ResourceReferenceRegistry
{
/** Log for reporting. */
private static final Logger log = LoggerFactory.getLogger(ResourceReferenceRegistry.class);
// Scan classes and its superclasses for static ResourceReference fields. For each
// RR field found, the callback method is called and the RR gets registered. It's kind of
// auto-register all RRs in your Component hierarchy.
private ClassScanner scanner = new ClassScanner()
{
@Override
boolean foundResourceReference(final ResourceReference reference)
{
// register the RR found (static field of Scope class)
return registerResourceReference(reference);
}
};
// The Map (registry) maintaining the resource references
private final ConcurrentHashMap<Key, ResourceReference> map = Generics.newConcurrentHashMap();
// If combinations of parameters (Key) have no registered resource reference yet, a default
// resource reference can be created and added to the registry. The following list keeps track
// of all auto added references.
private Queue<Key> autoAddedQueue;
// max entries. If the queue is full and new references are auto generated, references are
// removed starting with the first entry and unregistered from the registry.
private int autoAddedCapacity = 1000;
/**
* A simple implementation of {@link IResourceReferenceFactory} that creates
* {@link PackageResourceReference}
*/
public static class DefaultResourceReferenceFactory implements IResourceReferenceFactory
{
@Override
public ResourceReference create(Key key)
{
ResourceReference result = null;
if (PackageResource.exists(key))
{
result = new PackageResourceReference(key);
}
return result;
}
}
/**
* The factory to use when a ResourceReference is not previously
* registered and a new instance should be create
*/
private IResourceReferenceFactory resourceReferenceFactory;
/**
* Constructor.
*
* <p>Uses DefaultResourceReferenceFactory to create ResourceReference when there is
* no registered one for the requested attributes</p>
*/
public ResourceReferenceRegistry()
{
this(new DefaultResourceReferenceFactory());
}
/**
* Constructor
*
* @param resourceReferenceFactory
* The factory that will create ResourceReference by Key when there is no registered one
*/
public ResourceReferenceRegistry(IResourceReferenceFactory resourceReferenceFactory)
{
this.resourceReferenceFactory = Args.notNull(resourceReferenceFactory, "resourceReferenceFactory");
// Initial the auto-add list for a maximum of 1000 entries
setAutoAddedCapacity(autoAddedCapacity);
}
/**
* Registers the given {@link ResourceReference}.
* <p>
* {@link ResourceReference#canBeRegistered()} must return <code>true</code>. Else, the resource
* reference will not be registered.
*
* @param reference
* the reference to register
* @return {@code true} if the resource was registered successfully or has been registered previously
* already.
*/
public final boolean registerResourceReference(final ResourceReference reference)
{
return null != _registerResourceReference(reference);
}
/**
* Registers the given {@link ResourceReference}.
* <p>
* {@link ResourceReference#canBeRegistered()} must return <code>true</code>. Else, the resource
* reference will not be registered.
*
* @param reference
* the reference to register
* @return {@code true} if the resource was registered successfully or has been registered previously
* already.
*/
private Key _registerResourceReference(final ResourceReference reference)
{
Args.notNull(reference, "reference");
if (reference.canBeRegistered())
{
Key key = reference.getKey();
map.putIfAbsent(key, reference);
return key;
}
log.warn("{} cannot be added to the registry.", reference.getClass().getName());
return null;
}
/**
* Unregisters a {@link ResourceReference} by its identifier.
*
* @param key
* the {@link ResourceReference}'s identifier
* @return The removed ResourceReference or {@code null} if the registry did not contain an entry for this key.
*/
public final ResourceReference unregisterResourceReference(final Key key)
{
Args.notNull(key, "key");
// remove from registry
ResourceReference removed = map.remove(key);
// remove from auto-added list, in case the RR was auto-added
if (autoAddedQueue != null)
{
autoAddedQueue.remove(key);
}
return removed;
}
/**
* Get a resource reference matching the parameters from the registry or if not found and
* requested, create an default resource reference and add it to the registry.
* <p>
* Part of the search is scanning the class (scope) and it's superclass for static
* ResourceReference fields. Found fields get registered automatically (but are different from
* auto-generated ResourceReferences).
*
* @see #createDefaultResourceReference(org.apache.wicket.request.resource.ResourceReference.Key)
* @see ClassScanner
*
* @param scope
* The scope of resource reference (e.g. the Component's class)
* @param name
* The name of resource reference (e.g. filename)
* @param locale
* see Component
* @param style
* see Component
* @param variation
* see Component
* @param strict
* If true, "weaker" combination of scope, name, locale etc. are not tested
* @param createIfNotFound
* If true a default resource reference is created if no entry can be found in the
* registry. The newly created resource reference will be added to the registry.
* @return Either the resource reference found in the registry or, if requested, a resource
* reference automatically created based on the parameters provided. The automatically
* created resource reference will automatically be added to the registry.
*/
public final ResourceReference getResourceReference(final Class<?> scope, final String name,
final Locale locale, final String style, final String variation, final boolean strict,
final boolean createIfNotFound)
{
return getResourceReference(new Key(scope.getName(), name, locale, style, variation),
strict, createIfNotFound);
}
/**
* Get a resource reference matching the parameters from the registry or if not found and
* requested, create an default resource reference and add it to the registry.
* <p>
* Part of the search is scanning the class (scope) and it's superclass for static
* ResourceReference fields. Found fields get registered automatically (but are different from
* auto-generated ResourceReferences).
*
* @see #createDefaultResourceReference(org.apache.wicket.request.resource.ResourceReference.Key)
* @see ClassScanner
*
* @param key
* The data making up the resource reference
* @param strict
* If true, "weaker" combination of scope, name, locale etc. are not tested
* @param createIfNotFound
* If true a default resource reference is created if no entry can be found in the
* registry. The newly created resource reference will be added to the registry.
* @return Either the resource reference found in the registry or, if requested, a resource
* reference automatically created based on the parameters provided. The automatically
* created resource reference will automatically be added to the registry.
*/
public final ResourceReference getResourceReference(final Key key, final boolean strict,
final boolean createIfNotFound)
{
ResourceReference resource = _getResourceReference(key.getScope(), key.getName(),
key.getLocale(), key.getStyle(), key.getVariation(), strict);
// Nothing found so far?
if (resource == null)
{
// Scan the class (scope) and it's super classes for static fields containing resource
// references. Such resources are registered as normal resource reference (not
// auto-added).
if (scanner.scanClass(key.getScopeClass()) > 0)
{
// At least one new resource reference got registered => Search the registry again
resource = _getResourceReference(key.getScope(), key.getName(), key.getLocale(),
key.getStyle(), key.getVariation(), strict);
}
// Still nothing found => Shall a new reference be auto-created?
if ((resource == null) && createIfNotFound)
{
resource = addDefaultResourceReference(key);
}
}
return resource;
}
/**
* Get a resource reference matching the parameters from the registry.
*
* @param scope
* The scope of resource reference (e.g. the Component's class)
* @param name
* The name of resource reference (e.g. filename)
* @param locale
* see Component
* @param style
* see Component
* @param variation
* see Component
* @param strict
* If true, "weaker" combination of scope, name, locale etc. are not tested
* @return Either the resource reference found in the registry or null if not found
*/
private ResourceReference _getResourceReference(final String scope, final String name,
final Locale locale, final String style, final String variation, final boolean strict)
{
// Create a registry key containing all of the relevant attributes
Key key = new Key(scope, name, locale, style, variation);
// Get resource reference matching exactly the attrs provided
ResourceReference res = map.get(key);
if ((res != null) || strict)
{
return res;
}
res = _getResourceReference(scope, name, locale, style, null, true);
if (res == null)
{
res = _getResourceReference(scope, name, locale, null, variation, true);
}
if (res == null)
{
res = _getResourceReference(scope, name, locale, null, null, true);
}
if (res == null)
{
res = _getResourceReference(scope, name, null, style, variation, true);
}
if (res == null)
{
res = _getResourceReference(scope, name, null, style, null, true);
}
if (res == null)
{
res = _getResourceReference(scope, name, null, null, variation, true);
}
if (res == null)
{
res = _getResourceReference(scope, name, null, null, null, true);
}
return res;
}
/**
* Creates a default resource reference and registers it.
*
* @param key
* the data making up the resource reference
* @return The default resource created
*/
private ResourceReference addDefaultResourceReference(final Key key)
{
// Can be subclassed to create other than PackagedResourceReference
ResourceReference reference = createDefaultResourceReference(key);
if (reference != null)
{
// number of RRs which can be auto-added is restricted (cache size). Remove entries, and
// unregister excessive ones, if needed.
enforceAutoAddedCacheSize(getAutoAddedCapacity());
// Register the new RR
_registerResourceReference(reference);
// Add it to the auto-added list
if (autoAddedQueue != null)
{
autoAddedQueue.add(key);
}
}
else
{
log.warn("A ResourceReference wont be created for a resource with key [{}] because it cannot be located.", key);
}
return reference;
}
/**
* The number of {@link ResourceReference}s which can be auto-added is restricted (cache size). Remove entries, and
* unregister excessive ones, if needed.
*
* @param maxSize
* Remove all entries, head first, until auto-added cache is smaller than maxSize.
*/
private void enforceAutoAddedCacheSize(int maxSize)
{
if (autoAddedQueue != null)
{
while (autoAddedQueue.size() > maxSize)
{
// remove entry from auto-added list
Key first = autoAddedQueue.remove();
// remove entry from registry
map.remove(first);
}
}
}
/**
* Creates a default resource reference in case no registry entry and it was requested to create
* one.
* <p>
* A {@link PackageResourceReference} will be created by default
*
* @param key
* the data making up the resource reference
* @return The {@link ResourceReference} created or {@code null} if not successful
*/
protected ResourceReference createDefaultResourceReference(final Key key)
{
IResourceReferenceFactory factory = getResourceReferenceFactory();
if (factory == null)
{
factory = new DefaultResourceReferenceFactory();
}
return factory.create(key);
}
/**
* Set the cache size in number of entries
*
* @param autoAddedCapacity
* A value < 0 will disable aging of auto-create resource references. They will be
* created, added to the registry and live their until manually removed or the
* application shuts down.
*/
public final void setAutoAddedCapacity(final int autoAddedCapacity)
{
// Disable aging of auto-added references?
if (autoAddedCapacity < 0)
{
// unregister all auto-added references
clearAutoAddedEntries();
// disable aging from now on
autoAddedQueue = null;
}
else
{
this.autoAddedCapacity = autoAddedCapacity;
if (autoAddedQueue == null)
{
autoAddedQueue = new ConcurrentLinkedQueue<Key>();
}
else
{
// remove all extra entries if necessary
enforceAutoAddedCacheSize(autoAddedCapacity);
}
}
}
/**
* Gets cache size in number of entries
*
* @return capacity
*/
public final int getAutoAddedCapacity()
{
return autoAddedCapacity;
}
/**
* Unregisters all auto-added Resource References
*/
public final void clearAutoAddedEntries()
{
enforceAutoAddedCacheSize(0);
}
/**
* @return Number of auto-generated (and registered) resource references.
*/
public final int getAutoAddedCacheSize()
{
return autoAddedQueue == null ? -1 : autoAddedQueue.size();
}
/**
* @return Number of registered resource references (normal and auto-generated)
*/
public final int getSize()
{
return map.size();
}
/**
* @return the factory that will create the resource reference by using the parsed
* {@link org.apache.wicket.request.resource.ResourceReference.Key}
*/
public IResourceReferenceFactory getResourceReferenceFactory()
{
return resourceReferenceFactory;
}
/**
* Sets the factory to use when a ResourceReference is not previously
* registered and a new instance should be created
*
* @param resourceReferenceFactory
* the factory that will create the resource reference by using the parsed
* {@link org.apache.wicket.request.resource.ResourceReference.Key}
*/
public void setResourceReferenceFactory(IResourceReferenceFactory resourceReferenceFactory)
{
this.resourceReferenceFactory = resourceReferenceFactory;
}
}