View Javadoc

1   /*
2    * Copyright 2004-2005 the original author or authors.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package net.sf.morph.transform;
17  
18  /**
19   * A copier used by a {@link net.sf.morph.transform.GraphTransformer} to 
20   * assist in the transformation of one object graph into another object graph.
21   * A node copier is responsible for transforming a single node in the graph.
22   * The GraphTransformer chooses the appropriate node transformer for each node
23   * in the object graph. 
24   * 
25   * @author Matt Sgarlata
26   * @since Feb 22, 2005
27   */
28  public interface NodeCopier extends Copier {
29  	
30  	/**
31  	 * Returns a version of the given source object that can be used multiple
32  	 * times by this copier. In most cases, a source object is reusable without
33  	 * changes and is simply returned. However, in some cases a source object
34  	 * may be a "throw-away" object that can only be used once. A good example
35  	 * of this is traversal objects like Iterators and Enumerations. For objects
36  	 * like these, the information must be copied to a reuseable object before
37  	 * being used
38  	 * 
39  	 * @param destinationClass
40  	 *            the destination class to which this source object will be
41  	 *            transformed
42  	 * @param source
43  	 *            a source object that will undergo a transformation by this
44  	 *            copier
45  	 * @return a reusable version of fthe source object
46  	 */
47  	public Object createReusableSource(Class destinationClass, Object source);
48  	
49  	/**
50  	 * Creates a new instance of the destination class that is capable of
51  	 * holding the information contained in the given source.
52  	 * 
53  	 * @param destinationClass
54  	 *            the type of the new instance to be returned
55  	 * @param source
56  	 *            the source to be transformed by this transformer
57  	 * @return the new instance
58  	 */
59  	public Object createNewInstance(Class destinationClass, Object source);
60  	
61  	/**
62  	 * Retrieves the transformer used to perform nested transformations.
63  	 * 
64  	 * @return the transformer used to perform nested transformations
65  	 */
66  	public Transformer getNestedTransformer();
67  	
68  	/**
69  	 * Sets the transformer used to perform nested transformations.
70  	 * 
71  	 * @param nestedTransformer
72  	 *            the transformer used to perform nested transformations
73  	 */
74  	public void setNestedTransformer(Transformer nestedTransformer);
75  	
76  }