/interpreter/tags/at2dist110511/src/edu/vub/at/objects/ATTypeTag.java

  1/**
  2 * AmbientTalk/2 Project
  3 * ATTypeTag.java created on 18-feb-2007 at 15:55:09
  4 * (c) Programming Technology Lab, 2006 - 2007
  5 * Authors: Tom Van Cutsem & Stijn Mostinckx
  6 * 
  7 * Permission is hereby granted, free of charge, to any person
  8 * obtaining a copy of this software and associated documentation
  9 * files (the "Software"), to deal in the Software without
 10 * restriction, including without limitation the rights to use,
 11 * copy, modify, merge, publish, distribute, sublicense, and/or
 12 * sell copies of the Software, and to permit persons to whom the
 13 * Software is furnished to do so, subject to the following
 14 * conditions:
 15 *
 16 * The above copyright notice and this permission notice shall be
 17 * included in all copies or substantial portions of the Software.
 18 *
 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 21 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 23 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 24 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 25 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 26 * OTHER DEALINGS IN THE SOFTWARE.
 27 */
 28package edu.vub.at.objects;
 29
 30import edu.vub.at.exceptions.InterpreterException;
 31import edu.vub.at.objects.grammar.ATSymbol;
 32
 33/**
 34 * The public interface to a native type tag object.
 35 * <p>
 36 * Type tags consist of two properties:
 37 * <ul>
 38 * <li>they have a unique name by which they can be identified across the network.
 39 *    In other words, the identity of a type is its name (= nominal typing).
 40 * <li>they have a list of supertypes: a type is then a subtype of these supertypes.
 41 * </ul>
 42 * <p>
 43 * Types have one important operation: one type can be tested to be a subtype of
 44 * another type.
 45 *  <p>
 46 * Type tags are very similar to empty Java-like interface types, and their main purpose
 47 * lies in the *classification* of objects. AmbientTalk Objects can be tagged with zero
 48 * or more type tags.
 49 *
 50 * @author tvcutsem
 51 */
 52public interface ATTypeTag extends ATObject {
 53
 54	/**
 55	 * Returns the name of this type tag.
 56	 * 
 57	 * @return an {@link ATSymbol} representing the unique name by which the type can be identified.
 58	 */
 59	public ATSymbol base_typeName() throws InterpreterException;
 60	
 61	/**
 62	 * Returns a table with the supertypes of this type tag.
 63	 * 
 64	 * @return an {@link ATTable} with the super types of the receiver type tags.
 65	 */
 66	public ATTable base_superTypes() throws InterpreterException;
 67	
 68	/**
 69	 * Returns true if this type tag is a subtype of a given type tag.
 70	 * <p>
 71	 * More specifically, what the native implementation (expressed in AmbientTalk syntax) does is:
 72	 * <p>	 
 73	 *	<code>
 74	 *  def isSubtypeOf(supertype) {
 75	 *		  (supertype.name() == name).or:
 76	 *			  { (supertypes.find: { |stype| stype.isSubtypeOf(supertype) }) != nil }
 77	 *	};
 78	 *  </code>
 79	 *  
 80	 * @param other a type.
 81	 * @return true if the receiver type is a subtype of the other type.
 82	 */
 83	public ATBoolean base_isSubtypeOf(ATTypeTag other) throws InterpreterException;
 84	
 85	/**
 86	 * Invoked on a type tag when the type tag is used to annotate asynchronous message sends.
 87	 * E.g. when invoking:
 88	 * <code>obj<-m(args)@Type</code>
 89	 * The interpreter will invoke:
 90	 * <code>Type.annotateMessage(msg)</code> where <tt>msg</tt> is the message <tt><-m(args)</tt>
 91	 * The return value of the annotate method is an extended message which will be used during
 92	 * message sending. When a message is annotated with multiple type tags, the annotate methods
 93	 * of these different type tags are chained to produce the final message.
 94	 * 
 95	 * @param originalMessage the message to annotate
 96	 * @return the annotated message (the message extended with metadata)
 97	 */
 98	public ATObject base_annotateMessage(ATObject originalMessage) throws InterpreterException;
 99	
100	/**
101	 * Invoked on a type tag when the type tag is used to annotate method definitions. 
102	 * E.g. when evaluating:
103	 * <code>def method(arg1, ..., argN) @Type { ... }</code>
104	 * the interpreter will invoke <code>Type.annotateMethod(meth)</code> where <tt>meth</tt>
105	 * is a method object with the given name, arguments and body. The return value of the 
106	 * annotateMethod is an extended method object which will be installed in the method 
107	 * dictionary. The object can override e.g. apply to intervene when the method is being
108	 * applied. When a method definition is annotated with multiple type tags, the annotate 
109	 * methods of these different type tags are chained to produced the final method object.
110	 * 
111	 * @param originalMethod the method to annotate
112	 * @return the annotated method (the method with additional metadata)
113	 */
114	public ATMethod base_annotateMethod(ATMethod originalMethod) throws InterpreterException;
115	
116}