org.mmbase.framework

Class Framework

java.lang.Object

org.mmbase.framework.Framework

Direct Known Subclasses:

BasicFramework

public abstract class Framework
extends Object

The MMBase Framework displays and processes components. Components consist of Blocks which typically are pieces of JSP. The framework uses an urlfilter FrameworkFilter that can be configured in 'config/framework.xml'.

Since:

MMBase-1.9

Version:

$Id$

Author:

Johannes Verelst, Pierre van Rooden, Michiel Meeuwissen, Nico Klasens, André van Toly

Field Summary

Fields

Modifier and Type	Field and Description
static Parameter<String>	BLOCK The proposed parameter if the framework can be explicitely requested a block to render.
static Parameter<String>	COMPONENT The proposed parameter if the framework can be explicitely requested a (block of a certain) component to render.
static String	COMPONENT_CLASS_KEY CSS-class to be used on block.
static String	COMPONENT_CURRENTUSER_KEY The components' block rendering may want to know that the node associated with the current user is.
static String	COMPONENT_ID_KEY CSS-id to be used on block.
static String	COMPONENT_INCLUDEPATH_KEY If a component's block implementation decides to support 'tree/leaf including' it can use this framework-provided path for it.
(package private) static Framework	framework Reference to the Framework singleton.
static Parameter<Node>	N A framework must be able to provide a node to the rendered blocks.
static String	NAMESPACE
static String	XSD

Constructor Summary

Constructors

Constructor and Description
Framework()

Method Summary

Modifier and Type	Method and Description
abstract Parameters	createParameters() Return a Parameters object that needs to be passed on to the getUrl() call.
abstract Parameters	createSettingValueParameters()
static Framework	getInstance() Returns the framework.
abstract String	getInternalUrl(String path, Map<String,?> params, Parameters frameworkParameters) Generates an URL to a resource to be called and included by a renderer.
abstract String	getName() Return the name of the framework
abstract Parameter<?>[]	getParameterDefinition()
abstract String	getProcessUrl(String path, Map<String,?> parameters, Parameters frameworkParameters, boolean escapeAmps)
abstract Block	getRenderingBlock(Parameters frameworkParameters) Returns the block, which is currently rendering, or null
abstract <C> C	getSettingValue(Setting<C> setting, Parameters parameters) Retrieves the value as configured by this framework for a certain Setting (which is always associated with a certain Component.
abstract String	getUrl(String path, Map<String,?> parameters, Parameters frameworkParameters, boolean escapeAmps) Return a (possibly modified) URL for a given path.
abstract String	getUserBuilder() Return the builder name that is used to store users.
abstract Node	getUserNode(Parameters frameworkParameters) Return an MMBase Node for the user currently using the framework.
abstract void	process(Processor processor, Parameters blockParameters, Parameters frameworkParameters) Processes a block.
abstract void	render(Renderer renderer, Parameters blockParameters, Parameters frameworkParameters, Writer w, WindowState state) Render content (such as HTML or XML) using a Renderer obtained from a component's block.
abstract <C> C	setSettingValue(Setting<C> setting, Parameters parameters, C value) See getSettingValue(org.mmbase.framework.Setting<C>, org.mmbase.util.functions.Parameters).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

framework

static Framework framework

Reference to the Framework singleton.

XSD

public static final String XSD

See Also:

Constant Field Values

NAMESPACE

public static final String NAMESPACE

See Also:

Constant Field Values

COMPONENT

public static final Parameter<String> COMPONENT

The proposed parameter if the framework can be explicitely requested a (block of a certain) component to render.

BLOCK

public static final Parameter<String> BLOCK

The proposed parameter if the framework can be explicitely requested a block to render.

COMPONENT_ID_KEY

public static final String COMPONENT_ID_KEY

CSS-id to be used on block. This key will be used by the framework to communicate it to the block. Normally put on the request.

See Also:

Constant Field Values

COMPONENT_CLASS_KEY

public static final String COMPONENT_CLASS_KEY

CSS-class to be used on block.

See Also:

Constant Field Values

COMPONENT_INCLUDEPATH_KEY

public static final String COMPONENT_INCLUDEPATH_KEY

If a component's block implementation decides to support 'tree/leaf including' it can use this framework-provided path for it. Not all frameworks would support it, but then you simply don't have tree-overriding.

See Also:

Constant Field Values

COMPONENT_CURRENTUSER_KEY

public static final String COMPONENT_CURRENTUSER_KEY

The components' block rendering may want to know that the node associated with the current user is.

Since:

MMBase-1.9.1

See Also:

Constant Field Values

N

public static final Parameter<Node> N

A framework must be able to provide a node to the rendered blocks. This parameter could indicate _which_ node.

To Do:

Not yet supported, so basic framework cannot yet support block which require a framework provided node.

Constructor Detail

Framework

public Framework()

Method Detail

getInstance

public static Framework getInstance()

Returns the framework. Never null.

Returns:

the framework

getName

public abstract String getName()

Return the name of the framework

Returns:

Name

getRenderingBlock

public abstract Block getRenderingBlock(Parameters frameworkParameters)

Returns the block, which is currently rendering, or null

createParameters

public abstract Parameters createParameters()

Return a Parameters object that needs to be passed on to the getUrl() call. Many components will be implemented as servlets, so will not work if the framework does not at least include Parameter.REQUEST and Parameter.RESPONSE. So it is recommended that those parameters are supported by the framework. The MMBase taglib component tag will e.g. auto-fill those parameters. Other parameters can be added using 'mm:frameworkparameter' A framework may create a different or expanded list of parameters, but is responsible for filling them properly. If the framework does not use the MMBase taglib for rendering of components, it needs to provide it's own mechanism to fill the above parameters with default values (such as through a servlet or portlet).

Returns:

Parameters

render

public abstract void render(Renderer renderer,
                            Parameters blockParameters,
                            Parameters frameworkParameters,
                            Writer w,
                            WindowState state)
                     throws FrameworkException

Render content (such as HTML or XML) using a Renderer obtained from a component's block. The framework decides on a (extra) class for the div which is to be rendered, which is put on the request as COMPONENT_CLASS_KEY.

Parameters:

renderer - the Renderer used to produce the content. This parameter is obtained using Block.getRenderer(org.mmbase.framework.Renderer.Type)

blockParameters - The parameters specific for the call of this renderer's block

frameworkParameters - The parameters that are required by the framework, such as the 'request' and 'cloud' objects

w - The writer where the code generated by the renderer is to be written (such as the jspWriter)

state - the window state in which the content should be rendered

Throws:

FrameworkException - when the renderer failed to create content or could not write data to the writer

process

public abstract void process(Processor processor,
                             Parameters blockParameters,
                             Parameters frameworkParameters)
                      throws FrameworkException

Processes a block. This method can change or se state information and should be called prior to rendering a component's block. A process does not generate content.

Parameters:

processor - the Processor used to produce the content. This parameter is obtained using Block.getProcessor()

blockParameters - The parameters specific for the call of this renderer's block.

frameworkParameters - The parameters that are required by the framework, such as the 'request' and 'cloud' objects.

Throws:

FrameworkException - when the process failed to run

getUserNode

public abstract Node getUserNode(Parameters frameworkParameters)

Return an MMBase Node for the user currently using the framework. It is recommended that this is implemented as is done in BasicFramework, so based on MMBase security only, and using a Parameter.CLOUD as a framework parameter. It can be implemented differently, if the framework chooses not to use MMBase security to distinguish between users.

Parameters:

frameworkParameters - The parameters that are required by the framework, such as the 'request' and 'cloud' objects.

getUserBuilder

public abstract String getUserBuilder()

Return the builder name that is used to store users. This will return the name of the nodemanager that returns the nodes from the getUserNode() method.

Throws:

UnsupportedOperationException

To Do:

What if the framework wants to return virtual nodes?

createSettingValueParameters

public abstract Parameters createSettingValueParameters()

See Also:

getSettingValue(Setting, Parameters), setSettingValue(Setting, Parameters, Object)

getSettingValue

public abstract <C> C getSettingValue(Setting<C> setting,
                                      Parameters parameters)

Retrieves the value as configured by this framework for a certain Setting (which is always associated with a certain Component. The framework can (and should) return the default values of the Setting if it does not know what to do. It can also administrate overridden values, e.g. in its own configuration file. Using the 'parameters' (created with createSettingValueParameters(), the Framework can also implement context specific values for a setting. It can e.g. use a request object, and store user specific value as cookies.

setSettingValue

public abstract <C> C setSettingValue(Setting<C> setting,
                                      Parameters parameters,
                                      C value)
                               throws SecurityException

See getSettingValue(org.mmbase.framework.Setting<C>, org.mmbase.util.functions.Parameters). Depending on the framework, the set value may not necessarily be persistent.

Throws:

SecurityException - If you are not allowed to change the setting.

getParameterDefinition

public abstract Parameter<?>[] getParameterDefinition()

getUrl

public abstract String getUrl(String path,
                              Map<String,?> parameters,
                              Parameters frameworkParameters,
                              boolean escapeAmps)
                       throws FrameworkException

Return a (possibly modified) URL for a given path. This method is called (for example) from within the mm:url tag, and can be exposed to the outside world. I.e. when within a components's head you use
<mm:url page="/css/style.css" />,
this method is called to determine the proper url (i.e., relative to the framework or component base). If you need treefile/leaffile type of functionality in your framework, you can implement that here in your code.

Parameters:

path - The path (generally a relative URL) to create an URL for.

parameters - Parameters The parameters to be passed to the page

frameworkParameters - The parameters that are required by the framework

escapeAmps - true if parameters should be added with an escaped & (&amp;). You should escape & when a URL is exposed (i.e. in HTML), but not if the url is for some reason called directly.

Returns:

An URL relative to the root of this web application (i.e. without a context path), Never null.

Throws:

FrameworkException - thrown when something goes wrong in the Framework

getProcessUrl

public abstract String getProcessUrl(String path,
                                     Map<String,?> parameters,
                                     Parameters frameworkParameters,
                                     boolean escapeAmps)
                              throws FrameworkException

Throws:

FrameworkException

getInternalUrl

public abstract String getInternalUrl(String path,
                                      Map<String,?> params,
                                      Parameters frameworkParameters)
                               throws FrameworkException

Generates an URL to a resource to be called and included by a renderer. Typically, this generates a URL to a jsp, called by a renderer such as the JspRenderer, who calls the resource using the RequestDispatcher. This method allows for frameworks to do some filtering on URLs (such as pretty URLs). You should generally not call this method unless you write a Renderer that depends on code or data from external resources.

Parameters:

path - The page (e.g. image/css) provided by the component to create an URL for

params - Extra parameters for that path

frameworkParameters - The parameters that are required by the framework, such as the 'request' and 'cloud' objects

Returns:

A valid internal URL, or null if nothing framework specific could be determined (this would make it possible to 'chain' frameworks).

Throws:

FrameworkException - thrown when something goes wrong in the Framework