1/*
2 * Copyright (c) 1997, 2013, 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
26package com.sun.xml.internal.ws.api.pipe.helper;
27
28import com.sun.xml.internal.ws.api.pipe.Pipe;
29import com.sun.xml.internal.ws.api.pipe.PipeCloner;
30import com.sun.xml.internal.ws.api.message.Packet;
31
32/**
33 * Default implementation of {@link Pipe} that is used as a filter.
34 *
35 * <p>
36 * A filter pipe works on a {@link Packet}, then pass it onto the next pipe.
37 *
38 *
39 * <h2>How do I implement a filter?</h2>
40 * <p>
41 * Filter {@link Pipe}s are ideal for those components that wish to
42 * do some of the followings:
43 *
44 * <dl>
45 * <dt><b>
46 * To read an incoming message and perform some work before the
47 * application (or more precisely the next pipe sees it)
48 * </b>
49 * <dd>
50 * Implement the {@link #process} method and do some processing before
51 * you pass the packet to the next pipe:
52 * <pre>
53 * process(request) {
54 *   doSomethingWith(request);
55 *   return next.process(request);
56 * }
57 * </pre>
58 *
59 *
60 * <dt><b>
61 * To intercept an incoming message and prevent the next pipe from seeing it.
62 * </b>
63 * <dd>
64 * Implement the {@link #process} method and do some processing,
65 * then do NOT pass the request onto the next pipe.
66 * <pre>
67 * process(request) {
68 *   if(isSomethingWrongWith(request))
69 *     return createErrorMessage();
70 *   else
71 *     return next.proces(request);
72 * }
73 * </pre>
74 *
75 * <dt><b>
76 * To post process a reply and possibly modify a message:
77 * </b>
78 * <dd>
79 * Implement the {@link #process} method and do some processing,
80 * then do NOT pass the request onto the next pipe.
81 * <pre>
82 * process(request) {
83 *   op = request.getMessage().getOperation();
84 *   reply = next.proces(request);
85 *   if(op is something I care) {
86 *     reply = playWith(reply);
87 *   }
88 *   return reply;
89 * }
90 * </pre>
91 *
92 * </dl>
93 *
94 * @author Kohsuke Kawaguchi
95 */
96public abstract class AbstractFilterPipeImpl extends AbstractPipeImpl {
97    /**
98     * Next pipe to call.
99     */
100    protected final Pipe next;
101
102    protected AbstractFilterPipeImpl(Pipe next) {
103        this.next = next;
104        assert next!=null;
105    }
106
107    protected AbstractFilterPipeImpl(AbstractFilterPipeImpl that, PipeCloner cloner) {
108        super(that, cloner);
109        this.next = cloner.copy(that.next);
110        assert next!=null;
111    }
112
113    public Packet process(Packet packet) {
114        return next.process(packet);
115    }
116
117    @Override
118    public void preDestroy() {
119        next.preDestroy();
120    }
121}
122