/*
 * Copyright (C) 1999-2004 <a href="mailto:mandarax@jbdietrich.com">Jens Dietrich</a>
 *
 * 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 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.
 *
 * 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
 */
package org.mandarax.kernel;


/**
 * General interface for logical entities used to build complex
 * logical entities from simple entities. In particular, this
 * includes predicates and functions (used to build fact and complex terms).
 * Instances should be identified (<code>equals()</code>) using name and structure!
 * @see org.mandarax.kernel.Predicate
 * @see org.mandarax.kernel.Function
 * @author <A HREF="mailto:mandarax@jbdietrich.com">Jens Dietrich</A>
 * @version 3.3.1 <9 August 2004>
 * @since 1.0
 */
public interface Constructor extends java.io.Serializable, SemanticsSupport {

    /**
     * Get the name of the object.
     * @return the name of the constructor
     */
    String getName();

    /**
     * Get the type structure of the object, e.g. the types of terms
     * that can be used with this constructor.
     * @return the structure of this constructor
     */
    Class[] getStructure();

    /**
     * Perform the function or predicate using an array of terms as
     * parameters.
     * This usually can only succeed if all terms are constant and
     * the function has a semantic. E.g. if the function is (a wrapper around)
     * a java method, perform means invoking the method with the objects
     * wrapped by the constant terms as parameters.
     * <br>
     * The interface has been changed in 3.2 and takes now a session parameter. 
     * This is to support functionality such as concurrent simulations. The session 
     * object provides a context in which the operation is executed. The main
     * purpose of the session is to identify this context. Most applications
     * will not need this and can ignore this parameter.
     * @return the result of the perform operation
     * @param parameter an array of terms
     * @param session a session object
     * @throws java.lang.UnsupportedOperationException thrown if this constructor does not have a sematics and this operation cannot be supported
     * @throws java.lang.IllegalArgumentException
     */
    Object perform(Term[] parameter,Session session) throws IllegalArgumentException, UnsupportedOperationException;
}
