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 }