View Javadoc
1   /*
2    * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.xml.internal.ws.api.pipe;
27  
28  import java.util.Map;
29  
30  /**
31   * Clones the whole pipeline.
32   *
33   * <p>
34   * Since {@link Tube}s may form an arbitrary directed graph, someone needs
35   * to keep track of isomorphism for a clone to happen correctly. This class
36   * serves that role.
37   *
38   * @author Kohsuke Kawaguchi
39   */
40  public abstract class TubeCloner {
41      // Pipe to pipe, or tube to tube
42      public final Map<Object,Object> master2copy;
43  
44      /**
45       * Invoked by a client of a tube to clone the whole pipeline.
46       *
47       * <p>
48       * {@link Tube}s implementing the {@link Tube#copy(com.sun.xml.internal.ws.api.pipe.TubeCloner)} method
49       * shall use {@link #copy(Tube)} method.
50       *
51       * @param p
52       *      The entry point of a pipeline to be copied. must not be null.
53       * @return
54       *      The cloned pipeline. Always non-null.
55       */
56      @SuppressWarnings("deprecation")
57          public static Tube clone(Tube p) {
58          // we often want to downcast TubeCloner to PipeCloner,
59          // so let's create PipeCloner to make that possible
60          return new PipeClonerImpl().copy(p);
61      }
62  
63      // no need to be constructed publicly. always use the static clone method.
64      /*package*/ TubeCloner(Map<Object,Object> master2copy) {
65          this.master2copy = master2copy;
66      }
67  
68      /**
69       * Invoked by a {@link Tube#copy(com.sun.xml.internal.ws.api.pipe.TubeCloner)} implementation
70       * to copy a reference to another pipe.
71       *
72       * <p>
73       * This method is for {@link Tube} implementations, not for users.
74       *
75       * <p>
76       * If the given tube is already copied for this cloning episode,
77       * this method simply returns that reference. Otherwise it copies
78       * a tube, make a note, and returns a copied tube. This additional
79       * step ensures that a graph is cloned isomorphically correctly.
80       *
81       * <p>
82       * (Think about what happens when a graph is A->B, A->C, B->D, and C->D
83       * if you don't have this step.)
84       *
85       * @param t
86       *      The tube to be copied.
87       * @return
88       *      The cloned tube. Always non-null.
89       */
90          public abstract <T extends Tube> T copy(T t);
91  
92      /**
93       * This method must be called from within the copy constructor
94       * to notify that the copy was created.
95       *
96       * <p>
97       * When your pipe has references to other pipes,
98       * it's particularly important to call this method
99       * before you start copying the pipes you refer to,
100      * or else there's a chance of inifinite loop.
101      */
102     public abstract void add(Tube original, Tube copy);
103 }