Java tutorial
/* * This library is part of OpenCms - * the Open Source Content Management System * * Copyright (c) Alkacon Software GmbH (http://www.alkacon.com) * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * For further information about Alkacon Software GmbH, please see the * company website: http://www.alkacon.com * * For further information about OpenCms, please see the * project website: http://www.opencms.org * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * * * This file is based upon: * org.apache.commons.digester.CallMethodRule. * * Copyright 2001-2004 The Apache Software Foundation. * * Licensed 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.opencms.configuration; import org.opencms.file.CmsObject; import org.opencms.main.CmsLog; import org.apache.commons.beanutils.ConvertUtils; import org.apache.commons.beanutils.MethodUtils; import org.apache.commons.digester.Digester; import org.apache.commons.digester.Rule; import org.apache.commons.logging.Log; import org.xml.sax.Attributes; /** * Rule implementation that invokes a method on the (top-1) (parent) object, * passing as implicit first argument of type <code>{@link org.opencms.file.CmsObject}</code> * and as a further argument the top stack instance. <p> * * If no subsequent <code>CallParamRule</code> are matched for <code>CmsObject</code> * which is the case in the OpenCms usage the first argument <code>CmsObject</code> * will be null at method invocation time. <p> * This is an alternative for <code>{@link org.apache.commons.digester.SetNextRule}</code> * if a parent to child-property configuration has been done but the setter for that * property requires additional arguments that are only available at real runtime * of the application.<p> * * The top stack element (child) that has to be set is matched against the constructor * given <code>{@link java.lang.Class}[]</code>: It is used as argument on the position * where the <code>Class[]</code> has an instance of the same type as it's own <code>Class</code>.<p> * * @see org.apache.commons.digester.CallMethodRule * @see org.apache.commons.digester.SetNextRule * * @since 6.0.0 */ public class CmsSetNextRule extends Rule { /** The log object of this class. */ private static final Log LOG = CmsLog.getLog(CmsSetNextRule.class); /** * The body text collected from this element. */ protected String m_bodyText; /** * The method name to call on the parent object. */ protected String m_methodName; /** * The number of parameters to collect from <code>MethodParam</code> rules. * If this value is zero, a single parameter will be collected from the * body of this element. */ protected int m_paramCount; /** * The parameter types of the parameters to be collected. */ protected Class<?>[] m_paramTypes; /** * Should <code>MethodUtils.invokeExactMethod</code> be used for reflection. */ protected boolean m_useExactMatch; /** * location of the target object for the call, relative to the * top of the digester object stack. The default value of zero * means the target object is the one on top of the stack. */ private int m_targetOffset; /** * Construct a "call method" rule with the specified method name.<p> * * * The 1<sup>st</sup> argument of the method will be of type <code>{@link CmsObject}</code>. * It's value will remain null (except subsequent * <code>{@link org.apache.commons.digester.CallParamRule}</code> would put a value * which currently is impossible at initialization time within OpenCms).<p> * * The 2<sup>nd</sup> argument will be the top-stack element at digestion time. * That instance has to be of the same type as the <code>clazz</code> argument to succeed.<p> * * * @param methodName Method name of the parent method to call * @param clazz The class of the top-stack element (child) that will be present at digestion-time */ public CmsSetNextRule(String methodName, Class<?> clazz) { this(methodName, new Class[] { clazz }); } /** * Construct a "call method" rule with the specified method name * and additional parameters.<p> * * * The 1<sup>st</sup> argument of the method will be of type <code>{@link CmsObject}</code>. * It's value will remain null (except subsequent * <code>{@link org.apache.commons.digester.CallParamRule}</code> would put a value * which currently is impossible at initialization time within OpenCms).<p> * * The further arguments will be filled by the subsequent <code>{@link org.apache.commons.digester.CallParamRule}</code> * matches. If the first <code>Class</code> in the given array matches the top stack element * (child) that value will be used. If at digestion time no parameters are found for the given * types their values for invocation of the method remain null.<p> * * * @param methodName Method name of the parent method to call * @param clazzes an array with all parameter types for the method to invoke at digestion time */ public CmsSetNextRule(String methodName, Class<?>[] clazzes) { m_targetOffset = 0; m_methodName = methodName; m_paramCount = clazzes.length + 1; m_paramTypes = new Class[m_paramCount]; m_paramTypes[0] = CmsObject.class; System.arraycopy(clazzes, 0, m_paramTypes, 1, clazzes.length); } /** * Process the start of this element. * * @param attributes The attribute list for this element * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace * aware or the element has no namespace * @param name the local name if the parser is namespace aware, or just the element name otherwise * @throws Exception if something goes wrong */ @Override public void begin(String namespace, String name, Attributes attributes) throws Exception { // not now: 6.0.0 // digester.setLogger(CmsLog.getLog(digester.getClass())); // Push an array to capture the parameter values if necessary if (m_paramCount > 0) { Object[] parameters = new Object[m_paramCount]; for (int i = 0; i < parameters.length; i++) { parameters[i] = null; } digester.pushParams(parameters); } } /** * Process the body text of this element.<p> * * @param bodyText The body text of this element * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace * aware or the element has no namespace * @param name the local name if the parser is namespace aware, or just the element name otherwise * @throws Exception if something goes wrong */ @Override public void body(String namespace, String name, String bodyText) throws Exception { if (m_paramCount == 0) { m_bodyText = bodyText.trim(); } } /** * Process the end of this element.<p> * * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace * aware or the element has no namespace * @param name the local name if the parser is namespace aware, or just the element name otherwise * @throws Exception if something goes wrong */ @Override public void end(String namespace, String name) throws Exception { // Determine the target object for the method call: the parent object Object parent = digester.peek(1); Object child = digester.peek(0); // Retrieve or construct the parameter values array Object[] parameters = null; if (m_paramCount > 0) { parameters = (Object[]) digester.popParams(); if (LOG.isTraceEnabled()) { for (int i = 0, size = parameters.length; i < size; i++) { LOG.trace("[SetNextRuleWithParams](" + i + ")" + parameters[i]); } } // In the case where the target method takes a single parameter // and that parameter does not exist (the CallParamRule never // executed or the CallParamRule was intended to set the parameter // from an attribute but the attribute wasn't present etc) then // skip the method call. // // This is useful when a class has a "default" value that should // only be overridden if data is present in the XML. I don't // know why this should only apply to methods taking *one* // parameter, but it always has been so we can't change it now. if ((m_paramCount == 1) && (parameters[0] == null)) { return; } } else if (m_paramTypes.length != 0) { // Having paramCount == 0 and paramTypes.length == 1 indicates // that we have the special case where the target method has one // parameter being the body text of the current element. // There is no body text included in the source XML file, // so skip the method call if (m_bodyText == null) { return; } parameters = new Object[1]; parameters[0] = m_bodyText; if (m_paramTypes.length == 0) { m_paramTypes = new Class[1]; m_paramTypes[0] = String.class; } } else { // When paramCount is zero and paramTypes.length is zero it // means that we truly are calling a method with no parameters. // Nothing special needs to be done here. parameters = new Object[0]; } // Construct the parameter values array we will need // We only do the conversion if the param value is a String and // the specified paramType is not String. Object[] paramValues = new Object[m_paramTypes.length]; Class<?> propertyClass = child.getClass(); for (int i = 0; i < m_paramTypes.length; i++) { if (m_paramTypes[i] == propertyClass) { // implant the original child to set if Class matches: paramValues[i] = child; } else if ((parameters[i] == null) || ((parameters[i] instanceof String) && !String.class.isAssignableFrom(m_paramTypes[i]))) { // convert nulls and convert stringy parameters // for non-stringy param types if (parameters[i] == null) { paramValues[i] = null; } else { paramValues[i] = ConvertUtils.convert((String) parameters[i], m_paramTypes[i]); } } else { paramValues[i] = parameters[i]; } } if (parent == null) { StringBuffer sb = new StringBuffer(); sb.append("[SetNextRuleWithParams]{"); sb.append(digester.getMatch()); sb.append("} Call target is null ("); sb.append("targetOffset="); sb.append(m_targetOffset); sb.append(",stackdepth="); sb.append(digester.getCount()); sb.append(")"); throw new org.xml.sax.SAXException(sb.toString()); } // Invoke the required method on the top object if (LOG.isDebugEnabled()) { StringBuffer sb = new StringBuffer("[SetNextRuleWithParams]{"); sb.append(digester.getMatch()); sb.append("} Call "); sb.append(parent.getClass().getName()); sb.append("."); sb.append(m_methodName); sb.append("("); for (int i = 0; i < paramValues.length; i++) { if (i > 0) { sb.append(","); } if (paramValues[i] == null) { sb.append("null"); } else { sb.append(paramValues[i].toString()); } sb.append("/"); if (m_paramTypes[i] == null) { sb.append("null"); } else { sb.append(m_paramTypes[i].getName()); } } sb.append(")"); LOG.debug(sb.toString()); } Object result = null; if (m_useExactMatch) { // invoke using exact match result = MethodUtils.invokeExactMethod(parent, m_methodName, paramValues, m_paramTypes); } else { // invoke using fuzzier match result = MethodUtils.invokeMethod(parent, m_methodName, paramValues, m_paramTypes); } processMethodCallResult(result); } /** * Clean up after parsing is complete.<p> * * @param namespace the namespace URI of the matching element, or an empty string if the parser is not namespace * aware or the element has no namespace * @param name the local name if the parser is namespace aware, or just the element name otherwise * @throws Exception if something goes wrong */ public void finish(String namespace, String name) throws Exception { String dummy = name; dummy = namespace; dummy = null; m_bodyText = dummy; } /** * Returns true if <code>MethodUtils.invokeExactMethod</code> * shall be used for the reflection.<p> * * @return true if <code>MethodUtils.invokeExactMethod</code> * shall be used for the reflection. */ public boolean getUseExactMatch() { return m_useExactMatch; } /** * Set the associated digester.<p> * * The digester gets assigned to use the OpenCms conform logging * * If needed, this class loads the parameter classes from their names.<p> * * @param aDigester the associated digester to set */ @Override public void setDigester(Digester aDigester) { aDigester.setLogger(CmsLog.getLog(aDigester.getClass())); // call superclass super.setDigester(aDigester); } /** * Set the value to use for <code>MethodUtils.invokeExactMethod</code> * to use.<p> * * @param useExactMatch the value to use for <code>MethodUtils.invokeExactMethod</code> * to use */ public void setUseExactMatch(boolean useExactMatch) { m_useExactMatch = useExactMatch; } /** * Returns a printable version of this Rule.<p> * * @return a printable version of this Rule */ @Override public String toString() { StringBuffer sb = new StringBuffer("CallMethodRule["); sb.append("methodName="); sb.append(m_methodName); sb.append(", paramCount="); sb.append(m_paramCount); sb.append(", paramTypes={"); if (m_paramTypes != null) { for (int i = 0; i < m_paramTypes.length; i++) { if (i > 0) { sb.append(", "); } sb.append(m_paramTypes[i].getName()); } } sb.append("}"); sb.append("]"); return (sb.toString()); } /** * Subclasses may override this method to perform additional processing of the * invoked method's result.<p> * * @param result the Object returned by the method invoked, possibly null */ protected void processMethodCallResult(Object result) { // do nothing but to fool checkstyle if (result != null) { // nop } } }