001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.activemq.filter.function;
018
019import org.apache.activemq.filter.FunctionCallExpression;
020import org.apache.activemq.filter.MessageEvaluationContext;
021
022/**
023 * Interface required for objects that will be registered as functions for use in selectors.  Handles parse-
024 * time and evaluation-time operations.
025 */
026public interface FilterFunction {
027    /**
028     * Check whether the function, as it is used, is valid.  Checking arguments here will return errors
029     * to clients at the time invalid selectors are initially specified, rather than waiting until the selector is
030     * applied to a message.
031     *
032     * @param    FunctionCallExpression expr - the full expression of the function call, as used.
033     * @return true - if the function call is valid; false - otherwise.
034     */
035    public boolean isValid(FunctionCallExpression expr);
036
037    /**
038     * Determine whether the function, as it will be called, returns a boolean value.  Called during
039     * expression parsing after the full expression for the function call, including its arguments, has
040     * been parsed.  This allows functions with variable return types to function as boolean expressions in
041     * selectors without sacrificing parse-time checking.
042     *
043     * @param    FunctionCallExpression expr - the full expression of the function call, as used.
044     * @return true - if the function returns a boolean value for its use in the given expression;
045     * false - otherwise.
046     */
047    public boolean returnsBoolean(FunctionCallExpression expr);
048
049
050    /**
051     * Evaluate the function call in the given context.  The arguments must be evaluated, as-needed, by the
052     * function.  Note that boolean expressions must return Boolean objects.
053     *
054     * @param    FunctionCallExpression expr - the full expression of the function call, as used.
055     * @param    MessageEvaluationContext message - the context within which to evaluate the call.
056     */
057    public Object evaluate(FunctionCallExpression expr, MessageEvaluationContext message)
058            throws javax.jms.JMSException;
059}
060