1/*
2 * Copyright (c) 2005, 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 javax.xml.ws.soap;
27
28import javax.xml.ws.WebServiceFeature;
29import javax.xml.ws.WebServiceException;
30import javax.xml.ws.Endpoint;
31import javax.xml.ws.Service;
32
33/**
34 * This feature represents the use of MTOM with a
35 * web service.
36 *
37 * This feature can be used during the creation of SEI proxy, and
38 * {@link javax.xml.ws.Dispatch} instances on the client side and {@link Endpoint}
39 * instances on the server side. This feature cannot be used for {@link Service}
40 * instance creation on the client side.
41 *
42 * <p>
43 * The following describes the affects of this feature with respect
44 * to being enabled or disabled:
45 * <ul>
46 *  <li> ENABLED: In this Mode, MTOM will be enabled. A receiver MUST accept
47 * both a non-optimized and an optimized message, and a sender MAY send an
48 * optimized message, or a non-optimized message. The heuristics used by a
49 * sender to determine whether to use optimization or not are
50 * implementation-specific.
51 *  <li> DISABLED: In this Mode, MTOM will be disabled
52 * </ul>
53 * <p>
54 * The {@link #threshold} property can be used to set the threshold
55 * value used to determine when binary data should be XOP encoded.
56 *
57 * @since 1.6, JAX-WS 2.1
58 */
59public final class MTOMFeature extends WebServiceFeature {
60    /**
61     * Constant value identifying the MTOMFeature
62     */
63    public static final String ID = "http://www.w3.org/2004/08/soap/features/http-optimization";
64
65
66    /**
67     * Property for MTOM threshold value. This property serves as a hint when
68     * MTOM is enabled, binary data above this size in bytes SHOULD be sent
69     * as attachment.
70     * The value of this property MUST always be {@literal >=} 0. Default value is 0.
71     */
72    // should be changed to private final, keeping original modifier to keep backwards compatibility
73    protected int threshold;
74
75
76    /**
77     * Create an {@code MTOMFeature}.
78     * The instance created will be enabled.
79     */
80    public MTOMFeature() {
81        this.enabled = true;
82        this.threshold = 0;
83    }
84
85    /**
86     * Creates a {@code MTOMFeature}.
87     *
88     * @param enabled specifies if this feature should be enabled or not
89     */
90    public MTOMFeature(boolean enabled) {
91        this.enabled = enabled;
92        this.threshold = 0;
93    }
94
95
96    /**
97     * Creates a {@code MTOMFeature}.
98     * The instance created will be enabled.
99     *
100     * @param threshold the size in bytes that binary data SHOULD be before
101     * being sent as an attachment.
102     *
103     * @throws WebServiceException if threshold is {@literal <} 0
104     */
105    public MTOMFeature(int threshold) {
106        if (threshold < 0)
107            throw new WebServiceException("MTOMFeature.threshold must be >= 0, actual value: "+threshold);
108        this.enabled = true;
109        this.threshold = threshold;
110    }
111
112    /**
113     * Creates a {@code MTOMFeature}.
114     *
115     * @param enabled specifies if this feature should be enabled or not
116     * @param threshold the size in bytes that binary data SHOULD be before
117     * being sent as an attachment.
118     *
119     * @throws WebServiceException if threshold is {@literal <} 0
120     */
121    public MTOMFeature(boolean enabled, int threshold) {
122        if (threshold < 0)
123            throw new WebServiceException("MTOMFeature.threshold must be >= 0, actual value: "+threshold);
124        this.enabled = enabled;
125        this.threshold = threshold;
126    }
127
128    /**
129     * {@inheritDoc}
130     */
131    public String getID() {
132        return ID;
133    }
134
135    /**
136     * Gets the threshold value used to determine when binary data
137     * should be sent as an attachment.
138     *
139     * @return the current threshold size in bytes
140     */
141    public int getThreshold() {
142        return threshold;
143    }
144}
145