henning 2003/03/12 14:44:57
Modified: src/java/org/apache/turbine/services/pull PullService.java
TurbinePull.java TurbinePullService.java
Log:
Move constants into PullService Interface
Add lots of javadocs
Clean up tool cycle into initTool and refreshTool
Remove some static variables which should be class variables
Clean up code structures
Revision Changes Path
1.5 +39 -4
jakarta-turbine-2/src/java/org/apache/turbine/services/pull/PullService.java
Index: PullService.java
===================================================================
RCS file:
/home/cvs/jakarta-turbine-2/src/java/org/apache/turbine/services/pull/PullService.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- PullService.java 9 Mar 2003 03:06:30 -0000 1.4
+++ PullService.java 12 Mar 2003 22:44:57 -0000 1.5
@@ -85,18 +85,48 @@
* be specified as well.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Jason van Zyl</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]">Henning P. Schmiedehausen</a>
* @version $Id$
*/
-public interface PullService extends Service
+public interface PullService
+ extends Service
{
/**
* The key under which this service is stored in TurbineServices.
*/
- static final String SERVICE_NAME = "PullService";
+ String SERVICE_NAME = "PullService";
+
+ /** Property Key for the global tools */
+ String GLOBAL_TOOL = "tool.global";
+
+ /** Property Key for the request tools */
+ String REQUEST_TOOL = "tool.request";
+
+ /** Property Key for the session tools */
+ String SESSION_TOOL = "tool.session";
+
+ /** Property Key for the persistent tools */
+ String PERSISTENT_TOOL = "tool.persistent";
+
+ /** Property tag for application tool resources directory */
+ String TOOL_RESOURCES_DIR_KEY = "tools.resources.dir";
+
+ /** Default value for the application tool resources. This is relative to the
webapp root */
+ String TOOL_RESOURCES_DIR_DEFAULT = "resources";
+
+ /** Property tag for per request tool refreshing (for obvious reasons has no
effect for per-request tools) */
+ String TOOLS_PER_REQUEST_REFRESH_KEY = "tools.per.request.refresh";
+
+ /** Default value for per request tool refreshing */
+ boolean TOOLS_PER_REQUEST_REFRESH_DEFAULT = false;
+
/**
* Get the context containing global tools that will be
* use as part of the Turbine Pull Model.
+ *
+ * @return A Context object which contains the
+ * Global Tool instances.
*/
Context getGlobalContext();
@@ -114,12 +144,16 @@
/**
* Return the absolute path of the resources directory
* used by application tools.
+ *
+ * @return A directory path in the file system or null.
*/
String getAbsolutePathToResourcesDirectory();
/**
* Return the resources directory. This is relative
* to the webapp context.
+ *
+ * @return A directory path to the resources directory relative to the webapp
root or null.
*/
String getResourcesDirectory();
@@ -131,6 +165,8 @@
/**
* Shoud we refresh the tools
* on each request. For development purposes.
+ *
+ * returns true if we should refresh the tools on every request.
*/
boolean refreshToolsPerRequest();
@@ -141,5 +177,4 @@
* @param context a Velocity Context to release tools from
*/
void releaseTools(Context context);
-
}
1.4 +17 -9
jakarta-turbine-2/src/java/org/apache/turbine/services/pull/TurbinePull.java
Index: TurbinePull.java
===================================================================
RCS file:
/home/cvs/jakarta-turbine-2/src/java/org/apache/turbine/services/pull/TurbinePull.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- TurbinePull.java 9 Mar 2003 03:06:30 -0000 1.3
+++ TurbinePull.java 12 Mar 2003 22:44:57 -0000 1.4
@@ -56,6 +56,7 @@
import org.apache.turbine.services.TurbineServices;
import org.apache.turbine.util.RunData;
+
import org.apache.velocity.context.Context;
/**
@@ -67,6 +68,7 @@
*
* @author <a href="mailto:[EMAIL PROTECTED]">Jason van Zyl</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Daniel Rall</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]">Henning P. Schmiedehausen</a>
* @version $Id$
*/
public abstract class TurbinePull
@@ -84,11 +86,11 @@
}
/**
- * Get the ToolBox that was created by
- * Pull Service during early initialization. This
- * method is used by the various template services
- * that are available for use in Turbine, but
- * specifically the TurbineVelocityService.
+ * Get the context containing global tools that will be
+ * use as part of the Turbine Pull Model.
+ *
+ * @return A Context object which contains the
+ * Global Tool instances.
*/
public static final Context getGlobalContext()
{
@@ -113,8 +115,10 @@
}
/**
- * Return the absolute path of resources directory
- * where tools store resource information.
+ * Return the absolute path of the resources directory
+ * used by application tools.
+ *
+ * @return A directory path in the file system or null.
*/
public static final String getAbsolutePathToResourcesDirectory()
{
@@ -124,6 +128,8 @@
/**
* Return the resources directory. This is relative
* to the webapp context.
+ *
+ * @return A directory path to the resources directory relative to the webapp
root or null.
*/
public static final String getResourcesDirectory()
{
@@ -153,7 +159,7 @@
* to refresh itself on each request.
* <p>
* If there are objects that don't implement
- * application ApplicationTool then they won't
+ * the ApplicationTool interface, then they won't
* be refreshed.
*/
public static final void refreshGlobalTools()
@@ -164,6 +170,8 @@
/**
* Shoud we refresh the tools
* on each request. For development purposes.
+ *
+ * returns true if we should refresh the tools on every request.
*/
public static final boolean refreshToolsPerRequest()
{
1.14 +213 -204
jakarta-turbine-2/src/java/org/apache/turbine/services/pull/TurbinePullService.java
Index: TurbinePullService.java
===================================================================
RCS file:
/home/cvs/jakarta-turbine-2/src/java/org/apache/turbine/services/pull/TurbinePullService.java,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- TurbinePullService.java 9 Mar 2003 03:06:30 -0000 1.13
+++ TurbinePullService.java 12 Mar 2003 22:44:57 -0000 1.14
@@ -59,15 +59,19 @@
import java.util.List;
import org.apache.commons.configuration.Configuration;
+
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
+
import org.apache.turbine.Turbine;
import org.apache.turbine.om.security.User;
import org.apache.turbine.services.InitializationException;
import org.apache.turbine.services.TurbineBaseService;
-import org.apache.turbine.services.TurbineServices;
import org.apache.turbine.services.pool.PoolService;
+import org.apache.turbine.services.pool.TurbinePool;
+import org.apache.turbine.services.security.TurbineSecurity;
import org.apache.turbine.util.RunData;
+
import org.apache.velocity.VelocityContext;
import org.apache.velocity.context.Context;
@@ -143,12 +147,16 @@
* @author <a href="mailto:[EMAIL PROTECTED]">Henning P. Schmiedehausen</a>
* @version $Id$
*/
-public class TurbinePullService extends TurbineBaseService
+public class TurbinePullService
+ extends TurbineBaseService
implements PullService
{
/** Logging */
private static Log log = LogFactory.getLog(TurbinePullService.class);
+ /** Reference to the pool service */
+ private PoolService pool = TurbinePool.getService();
+
/**
* This is the container for the global web application
* tools that are used in conjunction with the
@@ -178,156 +186,125 @@
}
}
- /**
- * The lists that store tool data (name and class) for each
- * of the different type of tool. The Lists contain ToolData
- * objects.
- */
+ /** Internal list of global tools */
private List globalTools;
- private List requestTools;
- private List sessionTools;
- private List persistentTools;
- /**
- * The property tags that are used in conjunction with
- * TurbineResources.getOrderedValues(String) to get
- * our list of tools to instantiate (one tag for each
- * type of tool).
- */
- private static final String GLOBAL_TOOL = "tool.global";
- private static final String REQUEST_TOOL = "tool.request";
- private static final String SESSION_TOOL = "tool.session";
- private static final String PERSISTENT_TOOL = "tool.persistent";
-
- /**
- * Directory where application tool resources are stored.
- */
- private static String resourcesDirectory;
-
- /**
- * The absolute path the to resources directory used
- * by the application tools.
- */
- private static String absolutePathToResourcesDirectory;
+ /** Internal list of request tools */
+ private List requestTools;
- /**
- * Property tag for application tool resources directory
- */
- private static final String TOOL_RESOURCES_DIR
- = "tools.resources.dir";
+ /** Internal list of session tools */
+ private List sessionTools;
- /**
- * Default value for the application tool resources
- * directory. The location for the resources directory
- * is typically WEBAPP/resources.
- */
- private static final String TOOL_RESOURCES_DIR_DEFAULT
- = "/resources";
+ /** Internal list of persistent tools */
+ private List persistentTools;
- /**
- * Property tag for per request tool refreshing
- * (for obvious reasons has no effect for per-request tools)
- */
- private static final String TOOLS_PER_REQUEST_REFRESH =
- "tools.per.request.refresh";
+ /** Directory where application tool resources are stored.*/
+ private String resourcesDirectory;
- /**
- * Should we refresh the application tools on
- * a per request basis.
- */
- private static boolean refreshToolsPerRequest;
+ /** Should we refresh the application tools on a per request basis? */
+ private boolean refreshToolsPerRequest = false;
/**
* Called the first time the Service is used.
*/
- public void init() throws InitializationException
+ public void init()
+ throws InitializationException
{
try
{
- /*
- * Make sure to setInit(true) *inside* initPull()
- * because Tools may make calls back to the TurbinePull
- * static methods which may cause a recursive init
- * thing to happen.
- */
- initPull();
+ if (pool == null)
+ {
+ throw new Exception("Couldn't find pool service!");
+ }
+
+ initPullService();
+ // Make sure to setInit(true) because Tools may
+ // make calls back to the TurbinePull static methods
+ // which causes an init loop.
+ setInit(true);
+
+ initPullTools();
}
catch (Exception e)
{
throw new InitializationException(
- "TurbinePullService failed to initialize", e);
+ "TurbinePullService failed to initialize", e);
}
}
/**
- * Initialize the pull system
+ * Initialize the pull service
*
* @exception Exception, a generic exception.
*/
- private void initPull() throws Exception
+ private void initPullService()
+ throws Exception
{
+ // This is the per-service configuration, prefixed with services.PullService
Configuration conf = getConfiguration();
- /*
- * Get the resources directory that is specificed
- * in the TR.props or default to "/resources".
- */
- resourcesDirectory = conf.getString(TOOL_RESOURCES_DIR,
- TOOL_RESOURCES_DIR_DEFAULT);
-
- /*
- * Get absolute path to the resources directory.
- *
- * This should be done before the tools initialized
- * because a tool might need to know this value
- * for it to initialize correctly.
- */
- absolutePathToResourcesDirectory =
- Turbine.getRealPath(resourcesDirectory);
-
- /*
- * Should we refresh the tool box on a per
- * request basis.
- */
- refreshToolsPerRequest = conf.getBoolean(TOOLS_PER_REQUEST_REFRESH, false);
-
- /*
- * Log the fact that the application tool box will
- * be refreshed on a per request basis.
- */
+ // Get the resources directory that is specificed
+ // in the TR.props or default to "resources", relative to the webapp.
+ resourcesDirectory = conf.getString(
+ TOOL_RESOURCES_DIR_KEY,
+ TOOL_RESOURCES_DIR_DEFAULT);
+
+ // Should we refresh the tool box on a per
+ // request basis.
+ refreshToolsPerRequest =
+ conf.getBoolean(
+ TOOLS_PER_REQUEST_REFRESH_KEY,
+ TOOLS_PER_REQUEST_REFRESH_DEFAULT);
+
+ // Log the fact that the application tool box will
+ // be refreshed on a per request basis.
if (refreshToolsPerRequest)
+ {
log.info("Pull Model tools will "
- + "be refreshed on a per request basis.");
+ + "be refreshed on a per request basis.");
+ }
+ }
+
+ /**
+ * Initialize the pull tools. At this point, the
+ * service must be marked as initialized, because the
+ * tools may call the methods of this service via the
+ * static facade class TurbinePull.
+ *
+ * @exception Exception A problem happened when starting up
+ */
+ private void initPullTools()
+ throws Exception
+ {
+ // And for reasons I never really fully understood,
+ // the tools directive is toplevel without the service
+ // prefix. This is brain-damaged but for legacy reasons we
+ // keep this. So this is the global turbine configuration:
+ Configuration conf = Turbine.getConfiguration();
+
+ // Grab each list of tools that are to be used (for global scope,
+ // request scope, session scope and persistent scope tools).
+ // They are specified respectively in the TR.props like this:
+ //
+ // tool.global.ui = org.apache.turbine.util.pull.UIManager
+ // tool.global.mm = org.apache.turbine.util.pull.MessageManager
+ //
+ // tool.request.link = org.apache.turbine.util.template.TemplateLink;
+ //
+ // tool.session.basket = org.sample.util.ShoppingBasket;
+ //
+ // tool.persistent.ui =
org.apache.turbine.services.pull.util.PersistentUIManager
+
+ log.debug("Global Tools:");
+ globalTools = getTools(conf.subset(GLOBAL_TOOL));
+ log.debug("Request Tools:");
+ requestTools = getTools(conf.subset(REQUEST_TOOL));
+ log.debug("Session Tools:");
+ sessionTools = getTools(conf.subset(SESSION_TOOL));
+ log.debug("Persistent Tools:");
+ persistentTools = getTools(conf.subset(PERSISTENT_TOOL));
- /*
- * Make sure to set init true because Tools may make
- * calls back to the TurbinePull static methods which
- * may cause a recursive init thing to happen.
- */
- setInit(true);
-
- /*
- * Grab each list of tools that are to be used (for global scope,
- * request scope, session scope and persistent scope tools).
- * They are specified respectively in the TR.props like this:
- *
- * tool.global.ui = org.apache.turbine.util.pull.UIManager
- * tool.global.mm = org.apache.turbine.util.pull.MessageManager
- *
- * tool.request.link = org.apache.turbine.util.template.TemplateLink;
- *
- * tool.session.basket = org.sample.util.ShoppingBasket;
- *
- * tool.persistent.ui =
org.apache.turbine.services.pull.util.PersistentUIManager
- */
- globalTools = getTools(GLOBAL_TOOL);
- requestTools = getTools(REQUEST_TOOL);
- sessionTools = getTools(SESSION_TOOL);
- persistentTools = getTools(PERSISTENT_TOOL);
-
- /*
- * Create and populate the global context right now
- */
+ // Create and populate the global context right now
globalContext = new VelocityContext();
populateWithGlobalTools(globalContext);
}
@@ -336,52 +313,43 @@
* Retrieve the tool names and classes for the tools definied
* in the configuration file with the prefix given.
*
- * @param keyPrefix a String giving the property name prefix to look for
+ * @param toolConfig The part of the configuration describing some tools
*/
- private List getTools(String keyPrefix)
+ private List getTools(Configuration toolConfig)
{
- List classes = new ArrayList();
+ List tools = new ArrayList();
- Configuration toolResources =
- Turbine.getConfiguration().subset(keyPrefix);
-
- /*
- * There might not be any tools for this prefix
- * so return an empty list.
- */
- if (toolResources == null)
+ // There might not be any tools for this prefix
+ // so return an empty list.
+ if (toolConfig == null)
{
- return classes;
+ return tools;
}
- for (Iterator it = toolResources.getKeys(); it.hasNext();)
+ for (Iterator it = toolConfig.getKeys(); it.hasNext();)
{
String toolName = (String) it.next();
- String toolClassName = toolResources.getString(toolName);
+ String toolClassName = toolConfig.getString(toolName);
try
{
- /*
- * Create an instance of the tool class.
- */
+ // Create an instance of the tool class.
Class toolClass = Class.forName(toolClassName);
- /*
- * Add the tool to the list being built.
- */
- classes.add(new ToolData(toolName, toolClassName, toolClass));
+ // Add the tool to the list being built.
+ tools.add(new ToolData(toolName, toolClassName, toolClass));
- log.info("Instantiated tool class " + toolClassName
- + " to add to the context as '$" + toolName + "'");
+ log.info("Tool " + toolClassName
+ + " to add to the context as '$" + toolName + "'");
}
catch (Exception e)
{
- log.error("Cannot find tool class " + toolClassName
- + ", please check the name of the class.", e);
+ log.error("Cannot instantiate tool class "
+ + toolClassName + ": ", e);
}
}
- return classes;
+ return tools;
}
/**
@@ -411,14 +379,20 @@
// very similar, so the same method is used - the
// boolean parameter indicates whether get/setPerm is to be used
// rather than get/setTemp)
+
+ //
+ // Session Tool start right at the session once the user has been set
+ // while persistent Tools are started when the user has logged in
+ //
User user = data.getUser();
- if (user != null)
+
+ if (!TurbineSecurity.isAnonymousUser(user))
{
- populateWithSessionTools(sessionTools, context, user, false);
+ populateWithSessionTools(sessionTools, context, data, user, false);
if (user.hasLoggedIn())
{
- populateWithSessionTools(persistentTools, context, user, true);
+ populateWithSessionTools(persistentTools, context, data, user,
true);
}
}
}
@@ -436,19 +410,18 @@
try
{
Object tool = toolData.toolClass.newInstance();
- if (tool instanceof ApplicationTool)
- {
- // global tools are init'd with a null data parameter
- ((ApplicationTool) tool).init(null);
- }
+
+ // global tools are init'd with a null data parameter
+ initTool(tool, null);
+
// put the tool in the context
context.put(toolData.toolName, tool);
}
catch (Exception e)
{
- log.error(
- "Could not instantiate tool " + toolData.toolClassName
- + " to add to the context", e);
+ log.error("Could not instantiate global tool "
+ + toolData.toolName + " from a "
+ + toolData.toolClassName + " object", e);
}
}
}
@@ -461,30 +434,26 @@
*/
private void populateWithRequestTools(Context context, RunData data)
{
- // Get the PoolService to fetch object instances from
- PoolService pool = (PoolService)
- TurbineServices.getInstance().getService(PoolService.SERVICE_NAME);
-
// Iterate the tools
for (Iterator it = requestTools.iterator(); it.hasNext();)
{
ToolData toolData = (ToolData) it.next();
try
{
+ // Fetch Object through the Pool.
Object tool = pool.getInstance(toolData.toolClass);
- if (tool instanceof ApplicationTool)
- {
- // request tools are init'd with a RunData object
- ((ApplicationTool) tool).init(data);
- }
+
+ // request tools are init'd with a RunData object
+ initTool(tool, data);
+
// put the tool in the context
context.put(toolData.toolName, tool);
}
catch (Exception e)
{
- log.error(
- "Could not instantiate tool " + toolData.toolClassName
- + " to add to the context", e);
+ log.error("Could not instantiate request tool "
+ + toolData.toolName + " from a "
+ + toolData.toolClassName + " object", e);
}
}
}
@@ -495,18 +464,16 @@
* @param tools The list of tools with which to populate the
* session.
* @param context The context to populate.
+ * @param data The current RunData object
* @param user The <code>User</code> object whose storage to
* retrieve the tool from.
* @param usePerm Whether to retrieve the tools from the
* permanent storage (as opposed to the temporary storage).
*/
private void populateWithSessionTools(List tools, Context context,
- User user, boolean usePerm)
+ RunData data, User user,
+ boolean usePerm)
{
- // Get the PoolService to fetch object instances from
- PoolService pool = (PoolService)
- TurbineServices.getInstance().getService(PoolService.SERVICE_NAME);
-
// Iterate the tools
for (Iterator it = tools.iterator(); it.hasNext();)
{
@@ -520,19 +487,19 @@
// first try and fetch the tool from the user's
// hashtable
Object tool = usePerm
- ? user.getPerm(toolData.toolClassName)
- : user.getTemp(toolData.toolClassName);
+ ? user.getPerm(toolData.toolClassName)
+ : user.getTemp(toolData.toolClassName);
if (tool == null)
{
// if not there, an instance must be fetched from
// the pool
tool = pool.getInstance(toolData.toolClass);
- if (tool instanceof ApplicationTool)
- {
- // session tools are init'd with the User object
- ((ApplicationTool) tool).init(user);
- }
+
+ // session tools are init'd with the User object
+ initTool(tool, user);
+
+
// store the newly created tool in the user's hashtable
if (usePerm)
{
@@ -543,20 +510,37 @@
user.setTemp(toolData.toolClassName, tool);
}
}
- else if (refreshToolsPerRequest
- && tool instanceof ApplicationTool)
+
+ // *NOT* else
+ if(tool != null)
+ {
+ // This is a semantics change. In the old
+ // Turbine, Session tools were initialized and
+ // then refreshed every time they were pulled
+ // into the context if "refreshToolsPerRequest"
+ // was wanted.
+ //
+
+ if (refreshToolsPerRequest)
+ {
+ refreshTool(tool, data);
+ }
+
+ // put the tool in the context
+ log.debug("Adding " + tool + " to ctx as " +
toolData.toolName);
+ context.put(toolData.toolName, tool);
+ }
+ else
{
- ((ApplicationTool) tool).refresh();
+ log.info("Tool " + toolData.toolName + " was null, skipping
it.");
}
- // put the tool in the context
- context.put(toolData.toolName, tool);
}
}
catch (Exception e)
{
- log.error(
- "Could not instantiate tool " + toolData.toolClassName
- + " to add to the context", e);
+ log.error("Could not instantiate session tool "
+ + toolData.toolName + " from a "
+ + toolData.toolClassName + " object", e);
}
}
}
@@ -567,7 +551,7 @@
*/
public String getAbsolutePathToResourcesDirectory()
{
- return absolutePathToResourcesDirectory;
+ return Turbine.getRealPath(resourcesDirectory);
}
/**
@@ -588,12 +572,11 @@
*/
public void refreshGlobalTools()
{
- for (Iterator i = globalTools.iterator(); i.hasNext();)
+ for (Iterator it = globalTools.iterator(); it.hasNext();)
{
- ToolData toolData = (ToolData) i.next();
+ ToolData toolData = (ToolData) it.next();
Object tool = globalContext.get(toolData.toolName);
- if (tool instanceof ApplicationTool)
- ((ApplicationTool) tool).refresh();
+ refreshTool(tool, null);
}
}
@@ -614,13 +597,9 @@
*/
public void releaseTools(Context context)
{
- // Get the PoolService to release object instances to
- PoolService pool = (PoolService)
- TurbineServices.getInstance().getService(PoolService.SERVICE_NAME);
-
// only the request tools can be released - other scoped
// tools will have continuing references to them
- releaseTools(context, pool, requestTools);
+ releaseTools(context, requestTools);
}
/**
@@ -628,10 +607,9 @@
* to the pool
*
* @param context the Context containing the tools
- * @param pool an instance of the PoolService
* @param tools a List of ToolData objects
*/
- private void releaseTools(Context context, PoolService pool, List tools)
+ private void releaseTools(Context context, List tools)
{
for (Iterator it = tools.iterator(); it.hasNext();)
{
@@ -642,6 +620,37 @@
{
pool.putInstance(tool);
}
+ }
+ }
+
+ /**
+ * Initialized a given Tool with the passed init Object
+ *
+ * @param tool A Tool Object
+ * @param param The Init Parameter
+ *
+ * @throws Exception If anything went wrong.
+ */
+ private void initTool(Object tool, Object param)
+ throws Exception
+ {
+ if (tool instanceof ApplicationTool)
+ {
+ ((ApplicationTool) tool).init(param);
+ }
+ }
+
+ /**
+ * Refresh a given Tool.
+ *
+ * @param tool A Tool Object
+ * @param data The current RunData Object
+ */
+ private void refreshTool(Object tool, RunData data)
+ {
+ if (tool instanceof ApplicationTool)
+ {
+ ((ApplicationTool) tool).refresh();
}
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
