orbital.logic.functor
Class Functor.Specification

java.lang.Object
  orbital.logic.functor.Functor.Specification

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

Enclosing interface:

Functor

public static class Functor.Specification
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

Represents a signature and type specification belonging to a functor. This class provides an implicit interface which declares what methods a corresponding functor contains.

A functor f is specified by a signature declaration of the form

f/n: A₁×A₂×…×A_n→B

Such a declaration is represented as the functor signature pecification which specifies its arity n, argument-types A₁,...,A_n and return-type B as well as additional properties.

Functors to which the signature specification above belongs apply on

• argument₁ of type arg-type1 = A₁.
• argument₂ of type arg-type2 = A₂.
• ...
• argument_n of type arg-typen = A_n.
• return a value of type return-type = B.

The exact signature specification of a functor can either be defined explicitly with a sub interface of Functor that encapsulates those methods, or generically with an implicit interface introspected by getSpecification(Functor) with the use of reflection.

By convention, the methods affected by a specification are those with an invocation-signature of

 public return-type apply(arg-type1,arg-type2,...,arg-typen)
 public String toString()
 

Author:

André Platzer

See Also:

Functor, Class, Object.getClass(), Class.getMethods(), Class.getDeclaredMethods(), Method, Introspector, Serialized Form

Structure:

associated Functor

Constructor Summary

Functor.Specification(java.lang.Class[] parameterTypes)
Create an exact predicate specification with all properties declared.

Functor.Specification(java.lang.Class[] parameterTypes, java.lang.Class returnType)
Create an exact specification with all properties declared.

Functor.Specification(Functor.Specification[] parameterTypes, Functor.Specification returnType)
Create an exact specification with all properties declared.

Functor.Specification(int arity)
Create an exact specification with solely the arity set.

Functor.Specification(int arity, java.lang.Class returnType)
Create an exact specification with the arity and return-type set.

Functor.Specification(java.lang.String method, java.lang.Class[] parameterTypes, java.lang.Class returnType)
Create a non-conform specification with all properties declared.

Method Summary

int	arity() Specifies the arity n.
java.lang.Object	clone() Clones this specification.
int	compareTo(java.lang.Object o) Compares two specifications.
boolean	equals(java.lang.Object arg)
java.lang.reflect.Method	getMethod(java.lang.Class cls) Get the apply method in a given class that corresponds to this specification.
java.lang.Class[]	getParameterTypes() Specifies the argument-types of a Functor.
java.lang.Class	getReturnType() Specifies the return-type of a functor.
static Functor.Specification	getSpecification(Functor f) Introspect on a functor and get a specification of his exposed signature.
int	hashCode()
static java.lang.Object	invoke(Functor f, java.lang.Object[] args) Invokes the corresponding apply method of the Functor specified.
boolean	isApplicableTo(java.lang.Object[] args) Checks whether the type specification is compatible with the given list of arguments.
boolean	isCompatible(Functor.Specification b) Checks whether the given specification is compatible with this.
boolean	isConform(Functor f) Checks whether the given functor object is conform to this specification.
protected void	setParameterTypes(java.lang.Class[] newParameterTypes)
protected void	setReturnType(java.lang.Class newReturnType)
java.lang.String	toString() Get a human readable string representation of this specification of a functor.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Functor.Specification

public Functor.Specification(java.lang.Class[] parameterTypes,
                             java.lang.Class returnType)

Create an exact specification with all properties declared.

Parameters:

parameterTypes - an array of all parameter-types in order of calling. Its length is called arity.

returnType - the type of a resulting value.

Preconditions:

parameterTypes≠null ∧ returnType≠null

Functor.Specification

public Functor.Specification(Functor.Specification[] parameterTypes,
                             Functor.Specification returnType)

Create an exact specification with all properties declared. The types given are represented themselves as specifications.

Parameters:

parameterTypes - an array of all parameter-types in order of calling. Its length is called arity.

returnType - the type of a resulting value.

Preconditions:

parameterTypes≠null ∧ returnType≠null

Functor.Specification

public Functor.Specification(java.lang.Class[] parameterTypes)

Create an exact predicate specification with all properties declared.

The return-type will be Boolean.TYPE for representing predicates.

Parameters:

parameterTypes - an array of all parameter-types in order of calling. Its length is called arity.

Preconditions:

parameterTypes≠null

Functor.Specification

public Functor.Specification(int arity,
                             java.lang.Class returnType)

Create an exact specification with the arity and return-type set. The other properties will be set generically to the type java.lang.Object.

Parameters:

arity - the arity specified. The arity is the number of arguments needed in a call to apply.

returnType - the type of a resulting value.

Preconditions:

arity≥0 ∧ returnType≠null

Functor.Specification

public Functor.Specification(int arity)

Create an exact specification with solely the arity set. The other properties will be set most generically to the type java.lang.Object.

Parameters:

arity - the arity specified. The arity is the number of arguments needed in a call to apply.

Functor.Specification

public Functor.Specification(java.lang.String method,
                             java.lang.Class[] parameterTypes,
                             java.lang.Class returnType)

Create a non-conform specification with all properties declared. Other apply method names than "apply" are not fully conform with the general functor specification but may sometimes be useful as well.

Parameters:

method - the name of the method to call for applying the functor. Usually "apply".

parameterTypes - an array of all parameter-types in order of calling. Must have the length arity. The arity is the number of arguments needed in a call to apply.

returnType - the type of a resulting value.

Preconditions:

parameterTypes≠null ∧ returnType≠null ∧ method≠null

Postconditions:

◇abnormal(name of applyMethod)

Method Detail

clone

public java.lang.Object clone()

Clones this specification.

Overrides:

clone in class java.lang.Object

Postconditions:

RES != RES && RES != this && RES.equals(this)

compareTo

public int compareTo(java.lang.Object o)

Compares two specifications.

This implementation compares for arity in favor of parameter-types in favor of return-type.

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object arg)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

arity

public int arity()

Specifies the arity n. The arity is the number of arguments needed in a call to apply.

Returns:

the arity n of the specified Functor f/n.

Postconditions:

RES == getParameterTypes().length

getParameterTypes

public java.lang.Class[] getParameterTypes()

Specifies the argument-types of a Functor.

Returns:

an array (of size n, starting at index 0) that contains:

• type arg-type1 of Argument₁.
• type arg-type2 of Argument₂.
• ...
• type arg-typen of Argument_n.

setParameterTypes

protected void setParameterTypes(java.lang.Class[] newParameterTypes)

getReturnType

public java.lang.Class getReturnType()

Specifies the return-type of a functor.

Returns:

the type of the return-type value.

setReturnType

protected void setReturnType(java.lang.Class newReturnType)

isCompatible

public boolean isCompatible(Functor.Specification b)

Checks whether the given specification is compatible with this. measures compatibility.

This method will check the given specification against this. The given specification is compatible if it fulfills the arity and returnType of this specification as well as all arguments are assignement compatible with this, i.e. they are of the same kind (same type or a subtype).

Parameters:

b - the specification of the functor that is to be checked for compatibility with this specification.

Returns:

whether b ≤ this, i.e. if this specification is more general than b. This means that b is more special than this and fulfills the requirements of this specification, thus can be considered a subtype.

See Also:

isApplicableTo(Object[]), Class.isAssignableFrom(java.lang.Class)

isApplicableTo

public boolean isApplicableTo(java.lang.Object[] args)

Checks whether the type specification is compatible with the given list of arguments.

Parameters:

args - the arguments to check for compatibility with this symbol. null, or an array of length 0 can be used for zero arguments.

Returns:

whether the arguments are assignable to the required parameter types of this symbol. This especially includes whether the number of arguments matches this symbol's arity.

See Also:

isCompatible(Functor.Specification), Types.isApplicableTo(orbital.logic.sign.type.Type,orbital.logic.sign.Expression[])

Preconditions:

true

isConform

public boolean isConform(Functor f)

Checks whether the given functor object is conform to this specification.

Can be overwritten in order to perform checks in addition to type conformity.

Parameters:

f - the object to check for conformity to this specification. null does not conform to any specification.

Returns:

whether the object f is conform to this specification.

Since:

Orbital1.1

See Also:

Class.isInstance(Object)

getMethod

public java.lang.reflect.Method getMethod(java.lang.Class cls)
                                   throws java.lang.NoSuchMethodException

Get the apply method in a given class that corresponds to this specification.

Parameters:

cls - the class whose apply method to get. Which apply method of cls is chosen depends on this specification.

Returns:

the apply(...) method within the given class, according to this specification.

Throws:

java.lang.NoSuchMethodException - if the given class does not conform to this specification. This may be the case because cls does not provide the right apply method.

java.lang.SecurityException - if access to the information is denied, see Class.getMethod(String, Class[]).

Preconditions:

(∀o:cls) this.isConform(o)

toString

public java.lang.String toString()

Get a human readable string representation of this specification of a functor.

Overrides:

toString in class java.lang.Object

getSpecification

public static final Functor.Specification getSpecification(Functor f)
                                                    throws java.beans.IntrospectionException

Introspect on a functor and get a specification of his exposed signature.

This static method will analyze a functor object and generate a specification of his signature. It works for both, explicit and implicit interfaces.

If available, the introspection is improved by looking for a field

 static final Functor.Specification callTypeDeclaration;
 

in the corresponding class of the functor object.

Parameters:

f - the functor object to be analyzed.

Returns:

a signature specification object describing the target functor.

Throws:

java.beans.IntrospectionException - if an exception occurs during introspection.

See Also:

Types.declaredTypeOf(orbital.logic.functor.Functor)

Postconditions:

RES.isConform(f)

invoke

public static final java.lang.Object invoke(Functor f,
                                            java.lang.Object[] args)
                                     throws java.beans.IntrospectionException,
                                            java.lang.NoSuchMethodException,
                                            java.lang.IllegalArgumentException,
                                            java.lang.reflect.InvocationTargetException

Invokes the corresponding apply method of the Functor specified.

This method provides much dynamic flexibility when dealing with unknown functors at run-time. However note that due to the reflection required during the execution of this method, directly calling the apply method is preferred whenever possible.

Throws:

java.beans.IntrospectionException - if the functor is invalid or specifies none or too many apply-methods.

java.lang.NoSuchMethodException - if the functor made an explicit specification which he does not conform to.

java.lang.IllegalArgumentException - if the number of actual arguments and formal parameters differ, or if an unwrapping conversion fails.

java.lang.reflect.InvocationTargetException - if the underlying method throws an exception.

See Also:

getSpecification(Functor), getMethod(Class), Method.invoke(Object, Object[])