org.dihedron.patterns.visitor.Visitable Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dihedron-patterns Show documentation
b Library of more complex base functionalities (micro-patterns).
The newest version!
/**
 * Copyright (c) 2012-2014, Andrea Funto'. All rights reserved.
 * 
 * This file is part of the Dihedron Common Utilities library ("Commons").
 *
 * "Commons" 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 3 of the License, or (at your option) 
 * any later version.
 *
 * "Commons" 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 "Commons". If not, see .
 */

package org.dihedron.patterns.visitor;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotation used to identify objects that will be inspected during an object
 * visit; unless annotated, nested objects are treated as opaque types and not
 * recursed upon during a visit. Embedded objects, on the contrary, are treated
 * as recursion points and a new sub-visit is started on them. This behaviour 
 * also occurs on containers such as arrays, lists, maps and sets.
 * There are 4 possible behaviours:
 * treat a node as a "terminal", an opaque object that constitutes a node in 
 * itself
 * treat an object as a visitable object, an intermediate node in the visit, 
 * whose internal fields should be exposed as nodes
 * with collections, treat them as lists, sets, maps, arrays of opaque 
 * objects, so that each element is regarded as a terminal node
 * with collections, treat them as sets, lists, maps, array of visitable
 * objects, each of which is only an intermediate node in the visit
 * . This annotation provides a way to specify the visit behaviour:
 * when used on a plain object, it must be able to specify whether it is 
 * behaviour 1. or 2. that is intended; 
 * when used on a collection, it must specify which of the 4 possible 
 * approaches should be applied. 
 * . Since all 4 semantics apply to collections, and we may assume the 
 * lack of the annotation to mean behaviour 1. (no visit, opaque object),
 * there are 3 behaviours left that apply to collections, and this is represented 
 * through two boolean flags, one expressing wehther the node is visitable, one
 * expressing whether the nodes in a collection should be visitable or opaque.
 * The second flag will be ignored when applied to non-sollection nodes. 
 * 
 * @author Andrea Funto'
 */
@Retention(RetentionPolicy.RUNTIME) 
@Target({ ElementType.FIELD, ElementType.PARAMETER })
public @interface Visitable {
		
	/**
	 * This parameter is applied to all kind of objects, and expresses whether
	 * the node is visitable (it's only an intermediated node in the visit, with
	 * the {@code true} value) or it is an opaque object (expressed through the
	 * default {@code false} value.
	 * 
	 * @return
	 *   {@code true} to state that the object should be visited, {@code false}
	 *   to express that the node is opaque and should be regarded as a terminal
	 *   node in the visit.
	 */
	boolean value() default true;
	
	/**
	 * This parameter is only used when visiting a generic container: if set to
	 * {@code true}, each element in the collection (be it a {@code List}, a 
	 * {@code Map} or a {@code Set}) is visited recursively as a {@code VisitableNode}, 
	 * otherwise it is assumed to be a terminal node (a {@code JavaObject}).
	 * 
	 * @return
	 *   {@code false} by default, meaning that on generic container no recursion 
	 *   is applied; declare it as {@code true} to recurse iteration.
	 */
	boolean recurse() default true;
}