001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core;
015:
016: import org.w3c.dom.Node;
017:
018: /**
019: * Used to locate/replace text marks (variables) inside text based nodes
020: * (text nodes, comments, attribute values etc) without knowing the exact position in the DOM tree.
021: *
022: * <p>The variable syntax follows the JSP Expression Language notation:
023: * <code>${name}</code>.</p>
024: *
025: * @author Jose Maria Arranz Santamaria
026: * @see ItsNatServletRequest#createItsNatVariableResolver()
027: * @see ItsNatDocument#createItsNatVariableResolver()
028: * @see ItsNatSession#createItsNatVariableResolver()
029: * @see ItsNatServletContext#createItsNatVariableResolver()
030: */
031: public interface ItsNatVariableResolver {
032: /**
033: * Creates a variable resolver as a child of this resolver (bound to this resolver).
034: *
035: * @return a variable resolver bound to this resolver.
036: */
037: public ItsNatVariableResolver createItsNatVariableResolver();
038:
039: /**
040: * Returns the value associated to the specified name,
041: * only the local registry of this resolver is searched.
042: *
043: * @param name the name to search for.
044: * @return the value associated to the specified name or null if none is found.
045: * @see #setLocalVariable(String,Object)
046: * @see #removeLocalVariable(String)
047: */
048: public Object getLocalVariable(String name);
049:
050: /**
051: * Registers the specified variable name and value into the local registry
052: * of this resolver.
053: *
054: * @param name the variable name.
055: * @param value the variable value.
056: * @return the old value or null if not found.
057: * @see #getLocalVariable(String)
058: */
059: public Object setLocalVariable(String name, Object value);
060:
061: /**
062: * Unregisters the variable with the specified name from the local registry
063: * of this resolver.
064: *
065: * @param name the variable name.
066: * @return the variable value or null if not found.
067: * @see #getLocalVariable(String)
068: */
069: public Object removeLocalVariable(String name);
070:
071: /**
072: * Introspect the specified object registering all JavaBeans properties
073: * as local variables prefixed with the specified reference name.
074: *
075: * <p>Current implementation uses <code>jav.beans.Introspector.getBeanInfo(Class)</code>
076: * to get all JavaBeans properties. The reference name and property name are used
077: * to build a qualified name using a dot as separator, this
078: * qualified name is used to register as variable (e.g. "person.firstName"
079: * where "person" is the reference name and "firstName" is a JavaBeans property).</p>
080: *
081: * @param refName reference name used to qualify JavaBeans properties. If null or empty no prefix is added to property names.
082: * @param obj reference to the object value to introspect and register its JavaBeans properties.
083: */
084: public void introspect(String refName, Object obj);
085:
086: /**
087: * Returns the value associated to the specified name.
088: *
089: * <p>First of all the local registry is searched calling {@link #getLocalVariable(String)}
090: * if returns null then the "owner" of this resolver is used:
091: * </p>
092: * <p>If the variable resolver is a child of another variable resolver
093: * (was created with {@link #createItsNatVariableResolver()})
094: * then the method {@link #getVariable(String)} of the parent is called to continue searching.</p>
095: *
096: * <p>If the variable resolver was created with {@link org.itsnat.core.ItsNatServletContext#createItsNatVariableResolver()}
097: * then the method <code>ServletContext.getAttribute(String)</code> is called to continue searching.</p>
098: *
099: * <p>If the variable resolver was created with {@link org.itsnat.core.ItsNatSession#createItsNatVariableResolver()}
100: * then the method {@link org.itsnat.core.ItsNatSession#getAttribute(String)} is called to continue searching,
101: * if returns null then delegates to the method <code>ServletContext.getAttribute(String)</code>.</p>
102: *
103: * <p>If the variable resolver was created with {@link org.itsnat.core.ItsNatDocument#createItsNatVariableResolver()}
104: * then the method {@link org.itsnat.core.ItsNatDocument#getAttribute(String)} is called to continue searching,
105: * if returns null then delegates to the method {@link org.itsnat.core.ItsNatSession#getAttribute(String)},
106: * if returns null then delegates to the method <code>ServletContext.getAttribute(String)</code>.</p>
107: *
108: * @param name the name to search for.
109: * @return the value associated to the specified name or null if none is found.
110: */
111: public Object getVariable(String name);
112:
113: /**
114: * Locates and replaces any variable declaration with format ${name} contained into the specified string with
115: * the variable value converted to string (<code>Object.toString()</code>).
116: *
117: * <p>To obtain the value the method {@link #getVariable(String)} is called,
118: * if no variable is found the variable declaration is kept as is.</p>
119: *
120: * <p>The same variable may be repeated.</p>
121: *
122: * @param str the source string to resolve declared variables.
123: * @return the new string with replaced variables by values. If no variable was replaced (the original string is untouched) returns null.
124: * @see #resolve(org.w3c.dom.Node)
125: */
126: public String resolve(String str);
127:
128: /**
129: * Iterates recursively into the DOM subtree resolving (replacing) if possible any variable found with the
130: * format ${name} into element attributes and text based nodes.
131: *
132: * <p>The method {@link #resolve(String)} is used to process element attributes
133: * and content of text based nodes.
134: *
135: * @param node the node to resolve.
136: * @return true if some variable was resolved (replaced).
137: */
138: public boolean resolve(Node node);
139: }
|