org.omnifaces.resourcehandler.VersionedResourceHandler Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of omnifaces Show documentation
Jakarta Faces 3.0+ utility library
There is a newer version: 4.4.1
/*
 * Copyright OmniFaces
 *
 * 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
 *
 *     https://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.omnifaces.resourcehandler;

import static org.omnifaces.util.Faces.evaluateExpressionGet;
import static org.omnifaces.util.Faces.getInitParameter;
import static org.omnifaces.util.Utils.encodeURL;
import static org.omnifaces.util.Utils.isBlank;

import jakarta.faces.application.Resource;
import jakarta.faces.application.ResourceHandler;

import org.omnifaces.util.Lazy;

/**
 * Automatically adds version parameter with query string name v to all resource URLs so, in production mode
 * they will be cached forever (or as configured in web.xml),
 * but will not be stale when a new version of the app is deployed.
 * 
 * NOTE: if resource URL already has v query string parameter, or when it is URL-rewritten to not include
 * {@value jakarta.faces.application.ResourceHandler#RESOURCE_IDENTIFIER} path anymore, then these will be ignored.
 * 

 * Example:
 * 
 * faces-config.xml:
 * {@code
 *   
 *       org.omnifaces.resourcehandler.VersionedResourceHandler
 *   
 * }
 *
 * web.xml:
 * {@code
 *   
 *       
 *       com.sun.faces.defaultResourceMaxAge
 *       31536000000
 *   
 *   
 *       org.omnifaces.VERSIONED_RESOURCE_HANDLER_VERSION
 *       
 *       #{environmentInfo.version}
 *   
 * }
 * 
 * 
 * Example Code (GitHub)
 *
 * @author Lenny Primak
 * @since 3.9
 */
public class VersionedResourceHandler extends DefaultResourceHandler {

	/** The context parameter name to specify value of the version to be appended to the resource URL. */
	public static final String PARAM_NAME_VERSION = "org.omnifaces.VERSIONED_RESOURCE_HANDLER_VERSION";

	private static final String XHTML_EXTENSION = ".xhtml";
	private static final String VERSION_SUFFIX = "v=";
	private final Lazy versionString;

	/**
	 * Creates a new instance of this versioned resource handler which wraps the given resource handler.
	 * This will also initialize the version based on the context parameter.
	 * @param wrapped The resource handler to be wrapped.
	 */
	public VersionedResourceHandler(ResourceHandler wrapped) {
		super(wrapped);
		versionString = new Lazy<>(() -> encodeURL(evaluateExpressionGet(getInitParameter(PARAM_NAME_VERSION))));
	}

	@Override
	public Resource decorateResource(Resource resource) {
		if (resource == null || isBlank(versionString.get())) {
			return resource;
		}

		String requestPath = resource.getRequestPath();

		if (requestPath.contains('&' + VERSION_SUFFIX) || requestPath.contains('?' + VERSION_SUFFIX)) {
			// ignore already-versioned resources
			return resource;
		}
		else if (!requestPath.contains(ResourceHandler.RESOURCE_IDENTIFIER)) {
			// do not touch CDN resources
			return resource;
		}
		else if (resource.getResourceName().endsWith(XHTML_EXTENSION)) {
			// do not touch XHTML resources
			return resource;
		}
		else {
			requestPath += (requestPath.contains("?") ? '&' : '?') + VERSION_SUFFIX + versionString.get();
			return new RemappedResource(resource, requestPath);
		}
	}

}