Author: jdonnerstag
Date: Mon Nov 29 21:36:54 2010
New Revision: 1040311
URL: http://svn.apache.org/viewvc?rev=1040311&view=rev
Log:
mostly javadoc, not functional change
Modified:
wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupCache.java
wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupFactory.java
Modified:
wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupCache.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupCache.java?rev=1040311&r1=1040310&r2=1040311&view=diff
==============================================================================
--- wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupCache.java
(original)
+++ wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupCache.java
Mon Nov 29 21:36:54 2010
@@ -24,6 +24,7 @@ import org.apache.wicket.Application;
import org.apache.wicket.MarkupContainer;
import org.apache.wicket.WicketRuntimeException;
import org.apache.wicket.settings.IMarkupSettings;
+import org.apache.wicket.util.lang.Args;
import org.apache.wicket.util.listener.IChangeListener;
import org.apache.wicket.util.watch.IModifiable;
import org.apache.wicket.util.watch.IModificationWatcher;
@@ -67,7 +68,12 @@ public class MarkupCache implements IMar
private final Application application;
/**
- * @return The markup cache associated with the application
+ * A convenient helper to get the markup cache registered with the
application.
+ *
+ * @see {...@link Application#getMarkupSettings()}
+ * @see {...@link MarkupFactory#getMarkupCache()}
+ *
+ * @return The markup cache registered with the {...@link Application}
*/
public final static IMarkupCache get()
{
@@ -94,7 +100,7 @@ public class MarkupCache implements IMar
/**
* @see org.apache.wicket.markup.IMarkupCache#clear()
*/
- public final void clear()
+ public void clear()
{
markupCache.clear();
markupKeyCache.clear();
@@ -115,57 +121,46 @@ public class MarkupCache implements IMar
*/
public final IMarkupFragment removeMarkup(final String cacheKey)
{
- if (cacheKey == null)
- {
- throw new IllegalArgumentException("Parameter
'cacheKey' must not be null");
- }
+ Args.notNull(cacheKey, "cacheKey");
if (log.isDebugEnabled())
{
log.debug("Remove from cache: cacheKey=" + cacheKey);
}
- // Remove the markup and any other markup which depends on it
- // (inheritance)
- String locationString = (String)markupKeyCache.get(cacheKey);
+ // Remove the markup from the cache
+ CharSequence locationString = markupKeyCache.get(cacheKey);
IMarkupFragment markup = markupCache.get(locationString);
if (markup != null)
{
markupCache.remove(locationString);
- // In practice markup inheritance has probably not more
than 3 or 4
- // levels. And since markup reloading is only enabled
in development
- // mode, this max 4 iterations of the outer loop
shouldn't be a
- // problem.
+ // If a base markup file has been removed from the
cache, than
+ // the derived markup should be removed as well.
+
+ // Repeat until all depend resources have been removed
(count == 0)
int count;
do
{
count = 0;
- // If a base markup file has been removed from
the cache, than
- // the derived markup should be removed as well.
+ // Iterate though all entries of the cache
Iterator<CharSequence> iter =
markupCache.getKeys().iterator();
while (iter.hasNext())
{
- Markup cacheMarkup =
markupCache.get(iter.next());
- MarkupResourceStream resourceData =
cacheMarkup.getMarkupResourceStream()
- .getBaseMarkupResourceStream();
- if (resourceData != null)
+ CharSequence key = iter.next();
+
+ // Check if the markup associated with
key has a base markup. And if yes, test
+ // if that is cached.
+ if (isBaseMarkupCached(key))
{
- String baseCacheKey =
resourceData.getCacheKey();
- String baseLocationString =
(String)markupKeyCache.get(baseCacheKey);
- if (baseLocationString != null
&&
-
markupCache.get(baseLocationString) == null)
+ if (log.isDebugEnabled())
{
- if
(log.isDebugEnabled())
- {
-
log.debug("Remove from cache: cacheKey=" +
-
cacheMarkup.getMarkupResourceStream().getCacheKey());
- }
-
- iter.remove();
- count++;
+ log.debug("Remove from
cache: cacheKey=" + key);
}
+
+ iter.remove();
+ count++;
}
}
}
@@ -173,10 +168,10 @@ public class MarkupCache implements IMar
// And now remove all watcher entries associated with
markup
// resources no longer in the cache. Note that you can
not use
- // Application.get() since removeMarkup() will be call
from a
+ // Application.get() since removeMarkup() will be
called from a
// ModificationWatcher thread which has no associated
Application.
- final IModificationWatcher watcher =
application.getResourceSettings()
- .getResourceWatcher(true);
+ IModificationWatcher watcher =
application.getResourceSettings().getResourceWatcher(
+ true);
if (watcher != null)
{
Iterator<IModifiable> iter =
watcher.getEntries().iterator();
@@ -185,11 +180,7 @@ public class MarkupCache implements IMar
IModifiable modifiable = iter.next();
if (modifiable instanceof
MarkupResourceStream)
{
- MarkupResourceStream
resourceStream = (MarkupResourceStream)modifiable;
- String resourceCacheKey =
resourceStream.getCacheKey();
- String resouceLocationString =
(String)markupKeyCache.get(resourceCacheKey);
- if (resouceLocationString !=
null &&
-
markupCache.containsKey(resouceLocationString) == false)
+ if
(isMarkupCached((MarkupResourceStream)modifiable))
{
iter.remove();
}
@@ -201,6 +192,41 @@ public class MarkupCache implements IMar
}
/**
+ * @param key
+ * @return True, if base markup for entry with cache 'key' is available
in the cache as well.
+ */
+ private boolean isBaseMarkupCached(final CharSequence key)
+ {
+ // Get the markup associated with key
+ Markup markup = markupCache.get(key);
+
+ // Get the base markup resource stream from the markup
+ MarkupResourceStream resourceStream =
markup.getMarkupResourceStream()
+ .getBaseMarkupResourceStream();
+
+ // Is the base markup available in the cache?
+ return isMarkupCached(resourceStream);
+ }
+
+ /**
+ * @param resourceStream
+ * @return True if the markup is cached
+ */
+ private boolean isMarkupCached(final MarkupResourceStream
resourceStream)
+ {
+ if (resourceStream != null)
+ {
+ String key = resourceStream.getCacheKey();
+ CharSequence locationString = markupKeyCache.get(key);
+ if ((locationString != null) &&
(markupCache.get(locationString) == null))
+ {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
* @see org.apache.wicket.markup.IMarkupCache#size()
*/
public final int size()
Modified:
wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupFactory.java
URL:
http://svn.apache.org/viewvc/wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupFactory.java?rev=1040311&r1=1040310&r2=1040311&view=diff
==============================================================================
---
wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupFactory.java
(original)
+++
wicket/trunk/wicket/src/main/java/org/apache/wicket/markup/MarkupFactory.java
Mon Nov 29 21:36:54 2010
@@ -32,8 +32,8 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * Markup loading essentially is an autark modul of Wicket. MarkupFactory
provides all the means to
- * change defaults.
+ * Markup loading essentially is an self-sustaining modul of Wicket.
MarkupFactory is the entry
+ * point into that modul and provides all the means to change defaults.
*
* @author Juergen Donnerstag
*/
@@ -42,9 +42,6 @@ public class MarkupFactory
/** Log for reporting. */
private static final Logger log =
LoggerFactory.getLogger(MarkupFactory.class);
- /** The markup loader instance */
- private IMarkupLoader markupLoader;
-
/** A markup cache which will load the markup if required. */
private IMarkupCache markupCache;
@@ -67,28 +64,41 @@ public class MarkupFactory
}
/**
- * In case there is a need to extend the default chain of MarkupLoaders
+ * 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 MarkupLoader
+ * @return By default an instance of {...@link DefaultMarkupLoader}
will be returned. Via
+ * subclassing you may return your markup loader..
*/
public IMarkupLoader getMarkupLoader()
{
- if (markupLoader == null)
- {
- markupLoader = new DefaultMarkupLoader();
- }
- return markupLoader;
+ return new DefaultMarkupLoader();
}
/**
- * Create a new markup parser.
+ * 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>
- * In case you want to add you own markup filters, than subclass the
method and call
- * {...@link WicketMarkupParser#add(IMarkupFilter)} for your own filter
on the markup parser
- * returned.
+ * 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
- * @return A new markup parser
+ * The resource containing the markup
+ * @return A fresh instance of {...@link MarkupParser}
*/
public MarkupParser newMarkupParser(final MarkupResourceStream resource)
{
@@ -96,7 +106,7 @@ public class MarkupFactory
return new MarkupParser(new XmlPullParser(), resource)
{
/**
- * @see
org.apache.wicket.markup.WicketMarkupParser#onAppendMarkupFilter(org.apache.wicket.markup.parser.IMarkupFilter)
+ * @see
org.apache.wicket.markup.MarkupParser#onAppendMarkupFilter(org.apache.wicket.markup.parser.IMarkupFilter)
*/
@Override
protected IMarkupFilter onAppendMarkupFilter(final
IMarkupFilter filter)
@@ -107,13 +117,19 @@ public class MarkupFactory
}
/**
- * a) Allow subclasses to configure individual Wicket filters
- * <p>
- * b) Allow to replace default filter with extended one
+ * 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>
- * c) Allows to disable Wicket filters via returning false
*
* @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)
@@ -122,7 +138,12 @@ public class MarkupFactory
}
/**
- * The markup cache also loads the markup if not yet available in the
cache.
+ * 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.
*/
@@ -137,9 +158,8 @@ public class MarkupFactory
}
/**
- * return if markup cache has been initialized yet
- *
- * @return <code>true</code> if markup cache was already initialized,
<code>false</code> otherwise
+ * @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()
{
@@ -147,32 +167,31 @@ public class MarkupFactory
}
/**
- * Gets a fresh markup stream that contains the (immutable) markup
resource for this class.
+ * Get the markup associated with the container.
*
* @param container
- * The container the markup should be associated with
+ * The container to find the markup for
* @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 A stream of MarkupElement elements
+ * 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
*/
- public final IMarkupFragment getMarkup(final MarkupContainer container,
- final boolean enforceReload)
+ public final Markup getMarkup(final MarkupContainer container, final
boolean enforceReload)
{
return getMarkup(container, container.getClass(),
enforceReload);
}
/**
- * Gets a fresh markup stream that contains the (immutable) markup
resource for this class.
+ * Get the markup associated with the container.
*
* @param container
- * The container the markup should be associated with
+ * The container to find the markup for
* @param clazz
* Must be the container class or any of its super classes.
* @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 A stream of MarkupElement elements
+ * @return The markup associated with the container
*/
public final Markup getMarkup(final MarkupContainer container, final
Class<?> clazz,
final boolean enforceReload)
@@ -195,7 +214,7 @@ public class MarkupFactory
* Check if container has associated markup
*
* @param container
- * The container the markup should be associated with
+ * The container to find the markup for
* @return True if this markup container has associated markup
*/
public final boolean hasAssociatedMarkup(final MarkupContainer
container)
@@ -204,7 +223,11 @@ public class MarkupFactory
}
/**
- * Get the markup resource stream provider to be used
+ * 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
@@ -227,8 +250,6 @@ public class MarkupFactory
/**
* Create a new markup resource stream for the container.
- * <p>
- * Note: usually it will only called once, as the IResourceStream will
be cached by MarkupCache.
*
* @param container
* The MarkupContainer which requests to load the Markup
resource stream
