/*
* 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.cocoon.components.source.impl;
import java.io.IOException;
import java.net.MalformedURLException;
import java.util.Iterator;
import java.util.Map;
import org.apache.avalon.framework.activity.Disposable;
import org.apache.avalon.framework.configuration.Configurable;
import org.apache.avalon.framework.configuration.Configuration;
import org.apache.avalon.framework.configuration.ConfigurationException;
import org.apache.avalon.framework.container.ContainerUtil;
import org.apache.avalon.framework.logger.AbstractLogEnabled;
import org.apache.avalon.framework.parameters.Parameters;
import org.apache.avalon.framework.service.ServiceException;
import org.apache.avalon.framework.service.ServiceManager;
import org.apache.avalon.framework.service.Serviceable;
import org.apache.avalon.framework.thread.ThreadSafe;
import org.apache.excalibur.source.Source;
import org.apache.excalibur.source.SourceException;
import org.apache.excalibur.source.SourceFactory;
import org.apache.excalibur.source.SourceParameters;
import org.apache.excalibur.source.SourceResolver;
import org.apache.excalibur.source.SourceUtil;
import org.apache.excalibur.source.TraversableSource;
import org.apache.excalibur.source.URIAbsolutizer;
import org.apache.cocoon.caching.Cache;
import org.apache.cocoon.components.source.InspectableSource;
import org.apache.cocoon.components.source.helpers.SourceRefresher;
/**
* This class implements a proxy like source caches the contents of the source
* it wraps. This implementation can cache the content either for a given period
* of time or until an external event invalidates the cached response.
*
* <p>When using the timeout approach you have a choice between two separate
* revalidation strategies:</p>
*
* <ul>
* <li>Synchronously. This means that the cached contents are checked for validity
* and thrown out on the current thread.
* <li>Asynchronously. A runnable task is created to invalidate and update the
* cached response in the backgound.
* </ul>
*
* <h2>Protocol syntax</h2>
* <p>
* The URL needs to contain the URL of the cached source, an expiration
* period in seconds, and optionally a cache key:
* <code>cached:http://www.apache.org/[?cocoon:cache-expires=60][&cocoon:cache-name=main]</code>.
* </p>
* <p>
* The above examples shows how the real source <code>http://www.apache.org/</code>
* is wrapped and the cached contents is used for <code>60</code> seconds.
* The second querystring parameter instructs that the cache key be extended with the string
* <code>main</code>. This allows the use of multiple cache entries for the same source.
* </p>
* <p>
* This factory creates either instances of {@link org.apache.cocoon.components.source.impl.CachingSource}
* or {@link org.apache.cocoon.components.source.impl.TraversableCachingSource}
* depending on the whether the wrapped Source is an instance of TraversableSource.
* </p>
*
* <h2>Parameters</h2>
* <table><tbody>
* <tr>
* <th>cache-role (String)</th>
* <td>Role of component used as cache.</td>
* <td>opt</td>
* <td>String</td>
* <td><code>{@link Cache#ROLE}</code></td>
* </tr>
* <tr>
* <th>refresher-role (String)</th>
* <td>Role of component used for refreshing sources.</td>
* <td>opt</td>
* <td>String</td>
* <td><code>{@link org.apache.cocoon.components.source.helpers.SourceRefresher#ROLE}</code></td>
* </tr>
* <tr>
* <th>async (boolean)</th>
* <td>Indicated if the cached source should be refreshed asynchronously.</td>
* <td>opt</td>
* <td>String</td>
* <td><code>false</code></td>
* </tr>
* <tr>
* <th>event-aware (boolean)</th>
* <td>Whether to use event-based cache invalidation.</td>
* <td>opt</td>
* <td>String</td>
* <td><code>false</code></td>
* </tr>
* <tr>
* <th>default-expires (int)</th>
* <td>Default expiration value for if it is not specified on the Source itself.</td>
* <td>opt</td>
* <td>String</td>
* <td><code>-1</code></td>
* </tr>
* </tbody></table>
*
* @version $Id$
* @since 2.1.1
*/
public class CachingSourceFactory extends AbstractLogEnabled
implements Serviceable, Configurable, Disposable,
ThreadSafe, URIAbsolutizer, SourceFactory {
// ---------------------------------------------------- Constants
private static final String ASYNC_PARAM = "async";
private static final String EVENT_AWARE_PARAM = "event-aware";
private static final String CACHE_ROLE_PARAM = "cache-role";
private static final String REFRESHER_ROLE_PARAM = "refresher-role";
private static final String DEFAULT_EXPIRES_PARAM = "default-expires";
// ---------------------------------------------------- Instance variables
/** Protocol prefix / factory name */
private String scheme;
/** Asynchronous ? */
private boolean async;
/** Event aware ? */
private boolean eventAware;
/** The role of the cache */
private String cacheRole;
/** The role of the refresher */
private String refresherRole;
/** Default expires value */
private int defaultExpires;
/** Has the lazy initialization been done? */
private volatile boolean isInitialized;
/** The <code>ServiceManager</code> */
protected ServiceManager manager;
/** The {@link SourceResolver} */
protected SourceResolver resolver;
/** The refresher */
protected SourceRefresher refresher;
/** The cache */
protected Cache cache;
// ---------------------------------------------------- Lifecycle
public CachingSourceFactory() {
}
public void service(ServiceManager manager) {
this.manager = manager;
// Due to cyclic dependencies we can't lookup the resolver,
// the refresher or the cache until after the factory is
// initialized.
}
public void configure(Configuration configuration) throws ConfigurationException {
this.scheme = configuration.getAttribute("name");
Parameters parameters = Parameters.fromConfiguration(configuration);
// 'async' parameter
this.async = parameters.getParameterAsBoolean(ASYNC_PARAM, false);
// 'event-aware' parameter
this.eventAware = parameters.getParameterAsBoolean(EVENT_AWARE_PARAM, false);
// 'cache-role' parameter
this.cacheRole = parameters.getParameter(CACHE_ROLE_PARAM, Cache.ROLE);
// 'refresher-role' parameter
if (this.async) {
this.refresherRole = parameters.getParameter(REFRESHER_ROLE_PARAM, SourceRefresher.ROLE);
}
this.defaultExpires = parameters.getParameterAsInteger(DEFAULT_EXPIRES_PARAM, -1);
if (getLogger().isDebugEnabled()) {
getLogger().debug("Using cache " + this.cacheRole);
if (this.async) {
getLogger().debug("Using refresher " + this.refresherRole);
}
}
}
/**
* Lazy initialization of resolver and refresher because of
* cyclic dependencies.
*
* @throws SourceException
*/
private synchronized void lazyInitialize() throws SourceException {
if (this.isInitialized) {
// another thread finished initialization for us while
// we were waiting
return;
}
try {
this.resolver = (SourceResolver) this.manager.lookup(SourceResolver.ROLE);
} catch (ServiceException se) {
throw new SourceException("Missing service dependency: " + SourceResolver.ROLE, se);
}
try {
this.cache = (Cache) this.manager.lookup(this.cacheRole);
} catch (ServiceException se) {
throw new SourceException("Missing service dependency: " + this.cacheRole, se);
}
if (this.async) {
try {
this.refresher = (SourceRefresher) this.manager.lookup(this.refresherRole);
} catch (ServiceException se) {
throw new SourceException("Missing service dependency: " + this.refresherRole, se);
}
}
this.isInitialized = true;
}
/* (non-Javadoc)
* @see Disposable#dispose()
*/
public void dispose() {
if (this.refresher != null) {
this.manager.release(this.refresher);
this.refresher = null;
}
if (this.cache != null) {
this.manager.release(this.cache);
this.cache = null;
}
if (this.resolver != null) {
this.manager.release(this.resolver);
this.resolver = null;
}
this.manager = null;
}
// ---------------------------------------------------- SourceFactory implementation
protected String getScheme() {
return this.scheme;
}
protected boolean isAsync() {
return this.async;
}
/**
* Get a <code>Source</code> object.
* @param parameters This is optional.
*/
public Source getSource(final String location, final Map parameters)
throws MalformedURLException, IOException {
if (getLogger().isDebugEnabled() ) {
getLogger().debug("Creating source " + location);
}
// we must do lazy initialization because of cyclic dependencies
if (!this.isInitialized) {
lazyInitialize();
}
// snip the cache protocol
int index = location.indexOf(':');
if (index == -1) {
throw new MalformedURLException("This Source requires a subprotocol to be specified.");
}
String uri = location.substring(index + 1);
// parse the query string
SourceParameters sp = null;
index = uri.indexOf('?');
if (index != -1) {
sp = new SourceParameters(uri.substring(index + 1));
uri = uri.substring(0, index);
}
// put caching source specific query string parameters
// into a Parameters object
final Parameters params = new Parameters();
if (sp != null) {
SourceParameters remainingParameters = (SourceParameters) sp.clone();
final Iterator names = sp.getParameterNames();
while (names.hasNext()) {
String name = (String) names.next();
if (name.startsWith("cocoon:cache")) {
params.setParameter(name.substring("cocoon:".length()), sp.getParameter(name));
remainingParameters.removeParameter(name);
}
}
String queryString = remainingParameters.getEncodedQueryString();
if (queryString != null) {
uri += "?" + queryString;
}
}
int expires = params.getParameterAsInteger(CachingSource.CACHE_EXPIRES_PARAM, defaultExpires);
String cacheName = params.getParameter(CachingSource.CACHE_NAME_PARAM, null);
Source source = this.resolver.resolveURI(uri);
return createCachingSource(location, uri, source, expires, cacheName);
}
/**
* Actually creates a new CachingSource. Can be overriden in subclasses
*/
protected CachingSource createCachingSource(String uri,
String wrappedUri,
Source wrappedSource,
int expires,
String cacheName)
throws SourceException {
CachingSource source;
if (wrappedSource instanceof TraversableSource) {
if (wrappedSource instanceof InspectableSource) {
source = new InspectableTraversableCachingSource(this,
getScheme(),
uri,
wrappedUri,
(InspectableSource) wrappedSource,
expires,
cacheName,
isAsync(),
eventAware);
} else {
source = new TraversableCachingSource(this,
getScheme(),
uri,
wrappedUri,
(TraversableSource) wrappedSource,
expires,
cacheName,
isAsync(),
eventAware);
}
} else {
source = new CachingSource(getScheme(),
uri,
wrappedUri,
wrappedSource,
expires,
cacheName,
isAsync(),
eventAware);
}
// set the required components directly for speed
source.cache = this.cache;
ContainerUtil.enableLogging(source, getLogger());
try {
// call selected avalon lifecycle interfaces. Mmmh.
ContainerUtil.service(source, this.manager);
ContainerUtil.initialize(source);
} catch (ServiceException e) {
throw new SourceException("Unable to initialize source.", e);
} catch (Exception e) {
throw new SourceException("Unable to initialize source.", e);
}
if (this.async && expires > 0) {
// schedule it with the refresher
final Parameters params = new Parameters();
params.setParameter(SourceRefresher.PARAM_CACHE_INTERVAL,
String.valueOf(source.getExpiration()));
this.refresher.refresh(source.getCacheKey(), source.getURI(), params);
}
return source;
}
/**
* Release a {@link Source} object.
*/
public void release(Source source) {
if (source instanceof CachingSource) {
if (getLogger().isDebugEnabled() ) {
getLogger().debug("Releasing source " + source.getURI());
}
CachingSource caching = (CachingSource) source;
resolver.release(caching.source);
caching.dispose();
}
}
// ---------------------------------------------------- URIAbsolutizer implementation
/*
* (non-Javadoc)
* @see org.apache.excalibur.source.URIAbsolutizer#absolutize(java.lang.String, java.lang.String)
*/
public String absolutize(String baseURI, String location) {
return SourceUtil.absolutize(baseURI, location, true);
}
}