com.surelogic

Annotation Type Layer

@Documented
@Retention(value=RUNTIME)
@Target(value=PACKAGE)
public @interface Layer

Declares a named layer as well as the type set that types in the layer may refer to. A layer is a global entity, and it may be referred to by other annotations. Its name is qualified by the name of the package that it annotates. If the reference is within the same package the name does not need to be qualified.

To place more than one Layer annotation on a package, use the Layers annotation. It is a modeling error for a package to have both a Layer and a Layers annotation.

Semantics:

Places a structural constraint on the program's implementation. Types mapped into the layer are allowed to reference only types within the type sets or layers explicitly defined in the layer's may refer to clause.

Examples:

Declaring a layered model for an adventure-style game.

 @TypeSets({
   @TypeSet("UTIL=java.util & !(java.util.{Enumeration, Hashtable, Vector})"),
   @TypeSet("XML=org.jdom | UTIL | java.{io, net}")
 })
 @Layers({
   @Layer("MODEL may refer to UTIL"),
   @Layer("PERSISTENCE may refer to MODEL | XML"),
   @Layer("CONTROLLER may refer to MODEL | PERSISTENCE | java.io.File")
 })
 package com.surelogic.smallworld;
 

The UTIL typeset allows the use of all the types in the java.util package except for the Enumeration, Hashtable, and Vector classes. The XML typeset allows references to any type in the org.jdom package, any type in the UTIL typeset, and any type in the java.io and java.net packages.

Types mapped into the MODEL layer with the InLayer annotation may refer to any type in the UTIL typeset.

Types mapped into the PERSISTENCE layer with the InLayer annotation may refer to any type mapped into the MODEL layer and any type in the XML typeset.

Types mapped into the CONTROLLER layer with the InLayer annotation may refer to any type mapped into the MODEL layer, the PERSISTENCE layer, and the java.io.File type.

Javadoc usage notes:

This annotation may placed in Javadoc, which can be useful for Java 1.4 code which does not include language support for annotations, via the @annotate tag.

 /**
  * @annotate TypeSet("UTIL=java.util & !(java.util.{Enumeration, Hashtable, Vector})")
  * @annotate TypeSet("XML=org.jdom | UTIL | java.{io, net}")
  * @annotate Layer("MODEL may refer to UTIL"),
  * @annotate Layer("PERSISTENCE may refer to MODEL | XML"),
  * @annotate Layer("CONTROLLER may refer to MODEL | PERSISTENCE | java.io.File")
  */
 package com.surelogic.smallworld;
 

See Also:

InLayer, Layers, TypeSet

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value The name of the layer together with the may refer to type set.

Element Detail

value

public abstract String value

The name of the layer together with the may refer to type set. This set is declared using a constructive syntax shared with the other annotations. The attribute is restricted to strings that match the following grammar:

value = name "is" ["above" name *(", name) " ;"] "may" "refer" "to" no_layer_type_set_expr

no_layer_type_set_expr = no_layer_type_set_disjunct *("|" no_layer_type_set_disjunct) ; Set union

no_layer_type_set_disjunct = no_layer_type_set_conjunct *("&" no_layer_type_set_conjunct) ; Set intersection

no_layer_type_set_conjunct = ["!"] no_layer_type_set_leaf ; Set complement

no_layer_type_set_leaf = dotted_name ; Package name, type name, or no_layer_type set name
no_layer_type_set_leaf /= dotted_name "+" ; Package tree
no_layer_type_set_leaf /= dotted_name "." "{" name *(" ," name) "}" ; Union of packages/types
no_layer_type_set_leaf /= "(" no_layer_type_set_expr ")"

The "is above" clause names those layers are immediately below this layer; that is, those layers that are allowed to be referenced by types in this layer.

The union, intersection, and complement operators, as well as the parentheses have the obvious meanings, and standard precedence order. A package name signifies all the types in that package; a named type indicates a specific type. A dotted name is not allowed to refer to layer. A named type set stands for the type set specified by the given name, as defined by a @TypeSet annotation. The named type set is not allowed to refer to a layer, nor is any type set that it recursively references. The package tree suffix "+" indicates that all the types in the package and its subpackages are part of the set. The braces "{" "}" are syntactic sugar used to enumerate a union of packages/types that share the same prefix.