001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.ws.policy;
038:
039: import com.sun.xml.ws.policy.privateutil.LocalizationMessages;
040: import com.sun.xml.ws.policy.privateutil.PolicyUtils;
041: import java.util.Arrays;
042: import java.util.Collection;
043: import java.util.Collections;
044: import java.util.Iterator;
045: import java.util.LinkedList;
046: import java.util.List;
047: import java.util.Set;
048: import java.util.TreeSet;
049: import javax.xml.namespace.QName;
050:
051: /**
052: * A policy represents normalized policy as a wrapper of available policy alternatives represented by
053: * child {@link AssertionSet AssertionSets}.
054: *
055: * @author Fabian Ritzmann, Marek Potociar
056: */
057: public class Policy implements Iterable<AssertionSet> {
058: /**
059: * A string constant used in package private constructor to customize the object's toString() method output.
060: */
061: private static final String POLICY_TOSTRING_NAME = "policy";
062:
063: /**
064: * Constant represents empty list of assertion sets. This represents the content of a 'NULL' policy - a policy with
065: * no alternatives. The constant supports memory effective creation of 'NULL' policy objects.
066: */
067: private static final List<AssertionSet> NULL_POLICY_ASSERTION_SETS = Collections
068: .unmodifiableList(new LinkedList<AssertionSet>());
069:
070: /**
071: * Constant represents list of assertion sets with single empty assertion set. This represents the content of
072: * an 'EMPTY' policy - a policy with a single empty alternative. The constant supports memory effective creation
073: * of 'EMPTY' policy objects.
074: */
075: private static final List<AssertionSet> EMPTY_POLICY_ASSERTION_SETS = Collections
076: .unmodifiableList(new LinkedList<AssertionSet>(Arrays
077: .asList(new AssertionSet[] { AssertionSet
078: .emptyAssertionSet() })));
079:
080: /**
081: * Constant represents empty vocabulary of a 'NULL' or 'EMPTY' policies. The constant supports memory effective
082: * creation of 'NULL' and 'EMPTY' policy objects.
083: */
084: private static final Set<QName> EMPTY_VOCABULARY = Collections
085: .unmodifiableSet(new TreeSet<QName>(
086: PolicyUtils.Comparison.QNAME_COMPARATOR));
087:
088: /**
089: * Constant representation of all 'NULL' policies returned by createNullPolicy() factory method. This is to optimize
090: * the memory footprint.
091: */
092: private static final Policy ANONYMOUS_NULL_POLICY = new Policy(
093: null, null, NULL_POLICY_ASSERTION_SETS, EMPTY_VOCABULARY);
094:
095: /**
096: * Constant representation of all 'EMPTY' policies returned by createEmptyPolicy() factory method. This constant is
097: * to optimize the memory footprint.
098: */
099: private static final Policy ANONYMOUS_EMPTY_POLICY = new Policy(
100: null, null, EMPTY_POLICY_ASSERTION_SETS, EMPTY_VOCABULARY);
101:
102: /**
103: * Policy ID holder
104: */
105: private String policyId;
106:
107: /**
108: * Policy name holder
109: */
110: private String name;
111:
112: /**
113: * internal collection of policy alternatives
114: */
115: private final List<AssertionSet> assertionSets;
116:
117: /**
118: * internal collection of policy vocabulary entries (qualified names of all assertion types present in the policy expression)
119: */
120: private final Set<QName> vocabulary;
121:
122: /**
123: * immutable version of policy vocabulary that is made available to clients via getter method
124: */
125: private final Collection<QName> immutableVocabulary;
126:
127: /**
128: * policy object name used in a toString() method. This ensures that Policy class children can customize
129: * (via package private Policy constructors) the toString() method without having to override it.
130: */
131: private final String toStringName;
132:
133: /**
134: * The factory method creates an <b>immutable</b> policy instance which represents a <emph>'nothing allowed'</emph>
135: * policy expression.
136: *
137: * @return policy instance which represents a <emph>'nothing allowed'</emph> (no policy alternatives).
138: */
139: public static Policy createNullPolicy() {
140: return ANONYMOUS_NULL_POLICY;
141: }
142:
143: /**
144: * The factory method creates an <b>immutable</b> policy instance which represents a <emph>'anything allowed'</emph>
145: * policy expression.
146: *
147: * @return policy instance which represents a <emph>'anything allowed'</emph> (empty policy alternative with no plicy
148: * assertions prescribed).
149: */
150: public static Policy createEmptyPolicy() {
151: return ANONYMOUS_EMPTY_POLICY;
152: }
153:
154: /**
155: * The factory method creates an <b>immutable</b> policy instance which represents a <emph>'nothing allowed'</emph>
156: * policy expression.
157: *
158: * @param name global URI of the policy. May be {@code null}.
159: * @param policyId local URI of the policy. May be {@code null}.
160: * @return policy instance which represents a <emph>'nothing allowed'</emph> (no policy alternatives).
161: */
162: public static Policy createNullPolicy(final String name,
163: final String policyId) {
164: if (name == null && policyId == null) {
165: return ANONYMOUS_NULL_POLICY;
166: } else {
167: return new Policy(name, policyId,
168: NULL_POLICY_ASSERTION_SETS, EMPTY_VOCABULARY);
169: }
170: }
171:
172: /**
173: * The factory method creates an <b>immutable</b> policy instance which represents a <emph>'anything allowed'</emph>
174: * policy expression.
175: *
176: * @param name global URI of the policy. May be {@code null}.
177: * @param policyId local URI of the policy. May be {@code null}.
178: *
179: * @return policy instance which represents a <emph>'anything allowed'</emph> (empty policy alternative with no plicy
180: * assertions prescribed).
181: */
182: public static Policy createEmptyPolicy(final String name,
183: final String policyId) {
184: if (name == null && policyId == null) {
185: return ANONYMOUS_EMPTY_POLICY;
186: } else {
187: return new Policy(name, policyId,
188: EMPTY_POLICY_ASSERTION_SETS, EMPTY_VOCABULARY);
189: }
190: }
191:
192: /**
193: * The factory method creates an <b>immutable</b> policy instance which represents a policy expression with
194: * alternatives specified by {@code sets} input parameter. If the collection of policy alternatives is null or empty
195: * an object representing a 'NULL' policy expression is returned. However, in such case it is better to use
196: * {@link #createNullPolicy()} factory method directly.
197: *
198: * @param sets represents the collection of policy alternatives of the policy object created. During the creation of
199: * the new policy object, the content of the alternatives collection is copied into an internal policy object structure,
200: * thus any subsequent operations on the collection will have no impact on the newly constructed policy object.
201: *
202: * @return policy instance which represents the policy with given alternatives.
203: */
204: public static Policy createPolicy(
205: final Collection<AssertionSet> sets) {
206: if (sets == null || sets.isEmpty()) {
207: return createNullPolicy();
208: } else {
209: return new Policy(POLICY_TOSTRING_NAME, sets);
210: }
211: }
212:
213: /**
214: * The factory method creates an <b>immutable</b> policy instance which represents a policy expression with
215: * alternatives specified by {@code sets} input parameter. If the collection of policy alternatives is null or empty
216: * an object representing a 'NULL' policy expression is returned. However, in such case it is better to use
217: * {@link #createNullPolicy(String, String)} factory method directly.
218: *
219: * @param name global URI of the policy. May be {@code null}.
220: * @param policyId local URI of the policy. May be {@code null}.
221: * @param sets represents the collection of policy alternatives of the policy object created. During the creation of
222: * the new policy object, the content of the alternatives collection is copied into an internal policy object structure,
223: * thus any subsequent operations on the collection will have no impact on the newly constructed policy object.
224: *
225: * @return policy instance which represents the policy with given alternatives.
226: */
227: public static Policy createPolicy(final String name,
228: final String policyId, final Collection<AssertionSet> sets) {
229: if (sets == null || sets.isEmpty()) {
230: return createNullPolicy(name, policyId);
231: } else {
232: return new Policy(POLICY_TOSTRING_NAME, name, policyId,
233: sets);
234: }
235: }
236:
237: /**
238: * A most flexible policy object constructor that allows private creation of policy objects and direct setting
239: * of all its attributes.
240: *
241: * @param name global URI of the policy. May be {@code null}.
242: * @param policyId local URI of the policy. May be {@code null}.
243: * @param sets represents the collection of policy alternatives of the policy object created. The list is directly
244: * assigned to the policy object internal attribute. Subsequent manipulations on the collection must be handled with
245: * care.
246: * @param vocabulary represents the vocabulary of the policy object. Subsequent manipulations on the collection
247: * must be handled with care.
248: */
249: private Policy(final String name, final String policyId,
250: final List<AssertionSet> assertionSets,
251: final Set<QName> vocabulary) {
252: this .toStringName = POLICY_TOSTRING_NAME;
253: this .name = name;
254: this .policyId = policyId;
255: this .assertionSets = assertionSets;
256: this .vocabulary = vocabulary;
257: this .immutableVocabulary = Collections
258: .unmodifiableCollection(this .vocabulary);
259: }
260:
261: /**
262: * Constructor that should be overridden by child implementation. The constructor allows for easy toString() output
263: * customization.
264: *
265: * @param toStringName a general name of the object (such as 'policy' or 'nested policy') that will be used in the
266: * toString() method to identify the object.
267: * @param sets represents the collection of policy alternatives of the policy object created. During the creation of
268: * the new policy object, the content of the alternatives collection is copied into an internal policy object structure,
269: * thus any subsequent operations on the collection will have no impact on the newly constructed policy object. The
270: * collection may be {@code null} or empty. In such case a 'NULL' policy object is constructed.
271: */
272: Policy(final String toStringName,
273: final Collection<AssertionSet> sets) {
274: this .toStringName = toStringName;
275:
276: if (sets == null || sets.isEmpty()) {
277: this .assertionSets = NULL_POLICY_ASSERTION_SETS;
278: this .vocabulary = EMPTY_VOCABULARY;
279: this .immutableVocabulary = EMPTY_VOCABULARY;
280: } else {
281: this .assertionSets = new LinkedList<AssertionSet>();
282: this .vocabulary = new TreeSet<QName>(
283: PolicyUtils.Comparison.QNAME_COMPARATOR);
284: this .immutableVocabulary = Collections
285: .unmodifiableCollection(this .vocabulary);
286:
287: addAll(sets);
288: }
289: }
290:
291: /**
292: * Constructor that should be overridden by child implementation. The constructor allows for easy toString() output
293: * customization.
294: *
295: * @param toStringName a general name of the object (such as 'policy' or 'nested policy') that will be used in the
296: * toString() method to identify the object.
297: * @param name global URI of the policy. May be {@code null}.
298: * @param policyId local URI of the policy. May be {@code null}.
299: * @param sets represents the collection of policy alternatives of the policy object created. During the creation of
300: * the new policy object, the content of the alternatives collection is copied into an internal policy object structure,
301: * thus any subsequent operations on the collection will have no impact on the newly constructed policy object. The
302: * collection may be {@code null} or empty. In such case a 'NULL' policy object is constructed.
303: */
304: Policy(final String toStringName, final String name,
305: final String policyId, final Collection<AssertionSet> sets) {
306: this (toStringName, sets);
307: this .name = name;
308: this .policyId = policyId;
309: }
310:
311: /**
312: * Adds single alternative to the internal alternatives set of the policy object.
313: *
314: * @param set assertion set (policy alternative) object to be added. May be {@code null}; in such case the method
315: * returns false.
316: *
317: * @return {@code true} or {@code false} depending on whether the new alternative was added to the policy object or not.
318: */
319: private boolean add(final AssertionSet set) {
320: if (set == null) {
321: return false;
322: }
323:
324: if (this .assertionSets.contains(set)) {
325: return false;
326: } else {
327: this .assertionSets.add(set);
328: this .vocabulary.addAll(set.getVocabulary());
329: return true;
330: }
331: }
332:
333: /**
334: * Adds all alternatives from the input collection of assertion sets to the policy object's internal set of alternatives.
335: * The policy object's vocabulary structure is updated as well.
336: *
337: * @param sets collection of new alternatives. Must NOT be {@code null} or empty. The check for null or empty input
338: * parameter is performed with help of {@code assert} keyword, thus during the testing and development of this class
339: * {@code -ea} switch should be turned on for this class.
340: *
341: * @return {@code true} if all elements in the input collection were added to internal structure, {@code false} otherwise.
342: */
343: private boolean addAll(final Collection<AssertionSet> sets) {
344: assert (sets != null && !sets.isEmpty()) : LocalizationMessages
345: .WSP_0036_PRIVATE_METHOD_DOES_NOT_ACCEPT_NULL_OR_EMPTY_COLLECTION();
346:
347: boolean result = true;
348: for (AssertionSet set : sets) {
349: result &= add(set); // this is here to ensure that vocabulary is built correctly as well
350: }
351: Collections.sort(this .assertionSets);
352:
353: return result;
354: }
355:
356: Collection<AssertionSet> getContent() {
357: return assertionSets;
358: }
359:
360: /**
361: * Returns the policy identifier that serves as a local relative policy URI.
362: *
363: * @return policy identifier - a local relative policy URI. If no policy identifier is set, returns {@code null}.
364: */
365: public String getId() {
366: return policyId;
367: }
368:
369: /**
370: * Returns the policy name that serves as a global policy URI.
371: *
372: * @return policy name - a global policy URI. If no policy name is set, returns {@code null}.
373: */
374: public String getName() {
375: return name;
376: }
377:
378: /**
379: * Returns the policy ID or if that is null the policy name. May return null
380: * if both attributes are null.
381: *
382: * @see #getId()
383: * @see #getName()
384: * @return The policy ID if it was set, or the name or null if no attribute was set.
385: */
386: public String getIdOrName() {
387: if (policyId != null) {
388: return policyId;
389: }
390: return name;
391: }
392:
393: /**
394: * Method returns how many policy alternatives this policy instance contains.
395: *
396: * @return number of policy alternatives contained in this policy instance
397: */
398: public int getNumberOfAssertionSets() {
399: return assertionSets.size();
400: }
401:
402: /**
403: * A policy usually contains one or more assertion sets. Each assertion set
404: * corresponds to a policy alternative as defined by WS-Policy.
405: *
406: * @return An iterator to iterate through all contained assertion sets
407: */
408: public Iterator<AssertionSet> iterator() {
409: return assertionSets.iterator();
410: }
411:
412: /**
413: * Returns {@code true} if the policy instance represents "nothing allowed" policy expression
414: *
415: * @return {@code true} if the policy instance represents "nothing allowed" policy expression, {@code false} otherwise.
416: */
417: public boolean isNull() {
418: return assertionSets.size() == 0;
419: }
420:
421: /**
422: * Returns {@code true} if the policy instance represents "anything allowed" policy expression
423: *
424: * @return {@code true} if the policy instance represents "anything allowed" policy expression, {@code false} otherwise.
425: */
426: public boolean isEmpty() {
427: return assertionSets.size() == 1
428: && assertionSets.get(0).isEmpty();
429: }
430:
431: /**
432: * Returns true if the policy contains the assertion names with specified namespace in its vocabulary
433: *
434: * @param namespaceUri the assertion namespace URI (identifying assertion domain)
435: * @return {@code true}, if an assertion with the given name could be found in the policy vocabulary {@code false} otherwise.
436: */
437: public boolean contains(final String namespaceUri) {
438: for (QName entry : vocabulary) {
439: if (entry.getNamespaceURI().equals(namespaceUri)) {
440: return true;
441: }
442: }
443:
444: return false;
445: }
446:
447: /**
448: * Retrieves the vocabulary of this policy expression. The vocabulary is represented by an immutable collection of
449: * unique QName objects. Each of those objects represents single assertion type contained in the policy.
450: *
451: * @return immutable collection of assertion types contained in the policy (a policy vocabulary).
452: */
453: public Collection<QName> getVocabulary() {
454: return immutableVocabulary;
455: }
456:
457: /**
458: * Determines if the policy instance contains the assertion with the name specified in its vocabulary.
459: *
460: * @param assertionName the name of the assertion to be tested.
461: *
462: * @return {@code true} if the assertion with the specified name is part of the policy instance's vocabulary,
463: * {@code false} otherwise.
464: */
465: public boolean contains(final QName assertionName) {
466: return vocabulary.contains(assertionName);
467: }
468:
469: /**
470: * An {@code Object.equals(Object obj)} method override.
471: */
472: public boolean equals(final Object obj) {
473: if (this == obj) {
474: return true;
475: }
476:
477: if (!(obj instanceof Policy)) {
478: return false;
479: }
480:
481: final Policy that = (Policy) obj;
482:
483: boolean result = true;
484:
485: result = result && this .vocabulary.equals(that.vocabulary);
486: result = result
487: && this .assertionSets.size() == that.assertionSets
488: .size()
489: && this .assertionSets.containsAll(that.assertionSets);
490:
491: return result;
492: }
493:
494: /**
495: * An {@code Object.hashCode()} method override.
496: */
497: public int hashCode() {
498: int result = 17;
499:
500: result = 37 * result + vocabulary.hashCode();
501: result = 37 * result + assertionSets.hashCode();
502:
503: return result;
504: }
505:
506: /**
507: * An {@code Object.toString()} method override.
508: */
509: public String toString() {
510: return toString(0, new StringBuffer()).toString();
511: }
512:
513: /**
514: * A helper method that appends indented string representation of this instance to the input string buffer.
515: *
516: * @param indentLevel indentation level to be used.
517: * @param buffer buffer to be used for appending string representation of this instance
518: * @return modified buffer containing new string representation of the instance
519: */
520: StringBuffer toString(final int indentLevel,
521: final StringBuffer buffer) {
522: final String indent = PolicyUtils.Text
523: .createIndent(indentLevel);
524: final String innerIndent = PolicyUtils.Text
525: .createIndent(indentLevel + 1);
526: final String innerDoubleIndent = PolicyUtils.Text
527: .createIndent(indentLevel + 2);
528:
529: buffer.append(indent).append(toStringName).append(" {").append(
530: PolicyUtils.Text.NEW_LINE);
531: buffer.append(innerIndent).append("id = '").append(policyId)
532: .append('\'').append(PolicyUtils.Text.NEW_LINE);
533: buffer.append(innerIndent).append("name = '").append(name)
534: .append('\'').append(PolicyUtils.Text.NEW_LINE);
535:
536: buffer.append(innerIndent).append("vocabulary {").append(
537: PolicyUtils.Text.NEW_LINE);
538: if (vocabulary.isEmpty()) {
539: buffer.append(innerDoubleIndent).append("no entries")
540: .append(PolicyUtils.Text.NEW_LINE);
541: } else {
542: int index = 1;
543: for (QName entry : vocabulary) {
544: buffer.append(innerDoubleIndent).append(index++)
545: .append(". entry = '").append(
546: entry.getNamespaceURI()).append(':')
547: .append(entry.getLocalPart()).append('\'')
548: .append(PolicyUtils.Text.NEW_LINE);
549: }
550: }
551: buffer.append(innerIndent).append('}').append(
552: PolicyUtils.Text.NEW_LINE);
553:
554: if (assertionSets.isEmpty()) {
555: buffer.append(innerIndent).append("no assertion sets")
556: .append(PolicyUtils.Text.NEW_LINE);
557: } else {
558: for (AssertionSet set : assertionSets) {
559: set.toString(indentLevel + 1, buffer).append(
560: PolicyUtils.Text.NEW_LINE);
561: }
562: }
563:
564: buffer.append(indent).append('}');
565:
566: return buffer;
567: }
568: }
|