Java tutorial
/* * 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.markup; import java.io.IOException; import org.apache.wicket.Application; import org.apache.wicket.MarkupContainer; import org.apache.wicket.WicketRuntimeException; import org.apache.wicket.markup.loader.DefaultMarkupLoader; import org.apache.wicket.markup.loader.IMarkupLoader; import org.apache.wicket.markup.parser.IMarkupFilter; import org.apache.wicket.markup.parser.IXmlPullParser; import org.apache.wicket.markup.parser.XmlPullParser; import org.apache.wicket.util.lang.Args; import org.apache.wicket.util.resource.IResourceStream; import org.apache.wicket.util.resource.ResourceStreamNotFoundException; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * Factory to load markup either from cache or from a resource. * <p> * This class is the main entry point to load markup. Nothing else should be required by Components. * It manages caching markup as well as loading and merging (inheritance) of markup. * <p> * The markup returned is immutable as it gets re-used across multiple Component instances. * * @author Juergen Donnerstag */ public class MarkupFactory { /** Log for reporting. */ private static final Logger log = LoggerFactory.getLogger(MarkupFactory.class); /** A markup cache */ private IMarkupCache markupCache = null; /** The markup resource stream provider used by MarkupCache */ private IMarkupResourceStreamProvider markupResourceStreamProvider = null; /** * @return Gets the markup factory registered with the Wicket application */ public static MarkupFactory get() { return Application.get().getMarkupSettings().getMarkupFactory(); } /** * Construct. */ public MarkupFactory() { } /** * MarkupLoaders are responsible to find and load the markup for a component. That may be a * single file, but e.g. like in markup inheritance it could also be that the markup from * different sources must be merged. * * @return By default an instance of {@link DefaultMarkupLoader} will be returned. Via * subclassing you may return your own markup loader (chain). */ public IMarkupLoader getMarkupLoader() { return new DefaultMarkupLoader(); } /** * Create a new markup parser. Markup parsers read the markup and dissect it in Wicket relevant * pieces {@link MarkupElement}'s (kind of Wicket's DOM). * <p> * MarkupParser's can be extended by means of {@link IMarkupFilter}. You can add your own filter * as follows: * * <pre> * public MyMarkupFactory { * ... * public MarkupParser newMarkupParser(final MarkupResourceStream resource) { * MarkupParser parser = super.newMarkupParser(resource); * parser.add(new MyFilter()); * return parser; * } * } * </pre> * * @see #onAppendMarkupFilter(IMarkupFilter) * * @param resource * The resource containing the markup * @return A fresh instance of {@link MarkupParser} */ public MarkupParser newMarkupParser(final MarkupResourceStream resource) { // Markup parsers can not be re-used return new MarkupParser(newXmlPullParser(), resource) { @Override protected IMarkupFilter onAppendMarkupFilter(final IMarkupFilter filter) { return MarkupFactory.this.onAppendMarkupFilter(filter); } }; } /** * Subclasses can override this to use custom parsers. * * @return parser instance used by {@link MarkupParser} to parse markup. */ protected IXmlPullParser newXmlPullParser() { return new XmlPullParser(); } /** * A callback method that is invoked prior to any {@link IMarkupFilter} being registered with * {@link MarkupParser}. Hence it allows to: * <ul> * <li>tweak the default configuration of a filter</li> * <li>replace a filter with another one</li> * <li>avoid filters being used by returning null</li> * </ul> * Note that a new {@link MarkupParser} instance is created for each markup resources being * loaded. * <p> * * @param filter * The filter to be registered with the MarkupParser * @return The filter to be added. Null to ignore. */ protected IMarkupFilter onAppendMarkupFilter(final IMarkupFilter filter) { return filter; } /** * Get the markup cache which is registered with the factory. Since the factory is registered * with the application, only one cache per application exists. * <p> * Please note that markup cache is a pull through cache. It'll invoke a factory method * {@link #getMarkupResourceStream(MarkupContainer, Class)} to load the markup if not yet * available in the cache. * * @return Null, to disable caching. */ public IMarkupCache getMarkupCache() { if (markupCache == null) { markupCache = new MarkupCache(); } return markupCache; } /** * @return <code>true</code> if markup cache is available. Make sure you called * {@link #getMarkupCache()} at least once before to initialize the cache. */ public boolean hasMarkupCache() { return markupCache != null; } /** * Get the markup associated with the container. * * @param container * The container to find the markup for * @param enforceReload * If true, the cache will be ignored and all, including inherited markup files, will * be reloaded. Whatever is in the cache, it will be ignored * @return The markup associated with the container. Null, if the markup was not found or could * not yet be loaded (e.g. getMarkupType() == null). Wicket Exception in case of errors. */ public final Markup getMarkup(final MarkupContainer container, final boolean enforceReload) { return getMarkup(container, container.getClass(), enforceReload); } /** * Get the markup associated with the container. Check the cache first. If not found, than load * the markup and update the cache. * <p> * The clazz parameter usually can be null, except for base (inherited) markup. * <p> * There are several means to disable markup caching. Caching can be disabled alltogether - * getMarkupCache() return null -, or individually (cacheKey == null). * * @param container * The container to find the markup for * @param clazz * Must be the container class or any of its super classes. May be null. * @param enforceReload * The cache will be ignored and all, including inherited markup files, will be * reloaded. Whatever is in the cache, it will be ignored * @return The markup associated with the container. Null, if the markup was not found or could * not yet be loaded (e.g. getMarkupType() == null). Wicket Exception in case of errors. */ public final Markup getMarkup(final MarkupContainer container, final Class<?> clazz, final boolean enforceReload) { Args.notNull(container, "container"); if (checkMarkupType(container) == false) { // TODO improve: Result { boolean success, enum FailureReason {not found, not yet // available}, Markup markup } return null; } Class<?> containerClass = getContainerClass(container, clazz); IMarkupCache cache = getMarkupCache(); if (cache != null) { // MarkupCache acts as pull-through cache. It'll call the same loadMarkup() method as // below, if needed. // @TODO may be that can be changed. I don't like it too much. return cache.getMarkup(container, containerClass, enforceReload); } // Get the markup resource stream for the container (and super class) MarkupResourceStream markupResourceStream = getMarkupResourceStream(container, containerClass); return loadMarkup(container, markupResourceStream, enforceReload); } /** * Without a markup type we can not search for a file and we can not construct the cacheKey. We * can not even load associated markup as required for Panels. Though every MarkupContainer can * provide it's own type, by default they refer to the Page. Hence, no markup type is an * indicator, that the component or any of its parents, has not yet been added. * * @param container * The MarkupContainer which markup type has to checked * @return true, if container.getMarkupType() != null */ protected final boolean checkMarkupType(final MarkupContainer container) { if (container.getMarkupType() == null) { log.debug("Markup file not loaded, since the markup type is not yet available: {}", container); return false; } return true; } /** * Get the markup resource stream provider registered with the factory. * <p> * If the 'container' implements {@link IMarkupResourceStreamProvider}, the container itself * will be asked to provide the resource stream. Else Wicket's default implementation will be * used. * * @param container * The MarkupContainer requesting the markup resource stream * @return IMarkupResourceStreamProvider */ protected final IMarkupResourceStreamProvider getMarkupResourceStreamProvider(final MarkupContainer container) { if (container instanceof IMarkupResourceStreamProvider) { return (IMarkupResourceStreamProvider) container; } if (markupResourceStreamProvider == null) { markupResourceStreamProvider = new DefaultMarkupResourceStreamProvider(); } return markupResourceStreamProvider; } /** * Create a new markup resource stream for the container and optionally the Class. The Class * must be provided in case of base (inherited) markup. Else it might be null (standard use * case). * * @param container * The MarkupContainer which requests to load the Markup resource stream * @param clazz * Either the container class or any super class. Might be null. * @return A IResourceStream if the resource was found */ public final MarkupResourceStream getMarkupResourceStream(final MarkupContainer container, Class<?> clazz) { Args.notNull(container, "container"); if (checkMarkupType(container) == false) { // TODO improve: Result { boolean success, enum FailureReason {not found, not yet // available}, Markup markup } return null; } Class<?> containerClass = getContainerClass(container, clazz); // Who is going to provide the markup resource stream? // And ask the provider to locate the markup resource stream final IResourceStream resourceStream = getMarkupResourceStreamProvider(container) .getMarkupResourceStream(container, containerClass); // Found markup? if (resourceStream == null) { // TODO improve: Result { boolean success, enum FailureReason {not found, not yet // available}, Markup markup } return null; } if (resourceStream instanceof MarkupResourceStream) { return (MarkupResourceStream) resourceStream; } return new MarkupResourceStream(resourceStream, new ContainerInfo(container), containerClass); } /** * Gets and checks the container class * * @param container * The MarkupContainer which requests to load the Markup resource stream * @param clazz * Either null, or a super class of container * @return The container class to be used */ public final Class<?> getContainerClass(final MarkupContainer container, final Class<?> clazz) { Args.notNull(container, "container"); Class<?> containerClass = clazz; if (clazz == null) { containerClass = container.getClass(); } else if (!clazz.isAssignableFrom(container.getClass())) { throw new IllegalArgumentException("Parameter clazz must be an instance of " + container.getClass().getName() + ", but is a " + clazz.getName()); } return containerClass; } /** * Loads markup from a resource stream. It'll call the registered markup loader to load the * markup. * <p> * Though the 'enforceReload' attribute seem to imply that the cache is consulted to retrieve * the markup, the cache in fact is only checked for retrieving the base (inherited) markup. * Please see {@link #getMarkup(MarkupContainer, boolean)} as well. * * @param container * The original requesting markup container * @param markupResourceStream * The markup resource stream to load, if already known. * @param enforceReload * The cache will be ignored and all, including inherited markup files, will be * reloaded. Whatever is in the cache, it will be ignored * @return The markup. Null, if the markup was not found. Wicket Exception in case of errors. */ public final Markup loadMarkup(final MarkupContainer container, final MarkupResourceStream markupResourceStream, final boolean enforceReload) { // @TODO can markupResourceStream be replace with clazz??? Args.notNull(container, "container"); Args.notNull(markupResourceStream, "markupResourceStream"); if (checkMarkupType(container) == false) { // TODO improve: Result { boolean success, enum FailureReason {not found, not yet // available}, Markup markup } return null; } try { // The InheritedMarkupMarkupLoader needs to load the base markup. It'll do it via // MarkupFactory.getMarkup() as main entry point, which in turn allows to choose between // use or ignore the cache. That's why we need to propagate enforceReload to the markup // loader as well. // Markup loader is responsible to load the full markup for the container. In case of // markup inheritance, the markup must be merged from different markup files. It is the // merged markup which eventually will be cached, thus avoiding repetitive merge // operations, which always result in the same outcome. // The base markup will still be cached though, in order to avoid any unnecessary // reloads. The base markup itself might be merged as it might inherit from its base // class. return getMarkupLoader().loadMarkup(container, markupResourceStream, null, enforceReload); } catch (MarkupNotFoundException e) { // InheritedMarkupMarkupLoader will throw a MarkupNotFoundException in case the // <b>base</b> markup can not be found. log.error("Markup not found: " + e.getMessage(), e); // Catch exception and ignore => return null (markup not found) } catch (ResourceStreamNotFoundException e) { log.error("Markup not found: " + markupResourceStream, e); // Catch exception and ignore => return null (markup not found) } catch (IOException e) { log.error("Error while reading the markup " + markupResourceStream, e); // Wrap with wicket exception and re-throw throw new MarkupException(markupResourceStream, "IO error while reading markup: " + e.getMessage(), e); } catch (WicketRuntimeException e) { log.error("Error while reading the markup " + markupResourceStream, e); // re-throw throw e; } catch (RuntimeException e) { log.error("Error while reading the markup " + markupResourceStream, e); // Wrap with wicket exception and re-throw throw new MarkupException(markupResourceStream, "Error while reading the markup: " + e.getMessage(), e); } // Markup not found. Errors should throw a Wicket exception return null; } }