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
26package com.sun.xml.internal.ws.policy;
27
28import com.sun.xml.internal.ws.policy.privateutil.LocalizationMessages;
29import com.sun.xml.internal.ws.policy.privateutil.PolicyLogger;
30import com.sun.xml.internal.ws.policy.privateutil.PolicyUtils;
31import java.util.Collection;
32import java.util.LinkedList;
33import java.util.List;
34
35/**
36 * A PolicySubject is an entity (e.g., a port, operation, binding,
37 * service) with which a policy can be associated.
38 *
39 * @author Fabian Ritzmann
40 */
41public final class PolicySubject {
42    private static final PolicyLogger LOGGER = PolicyLogger.getLogger(PolicySubject.class);
43
44    private final List<Policy> policies = new LinkedList<Policy>();
45    private final Object subject;
46
47    /**
48     * Constructs a policy subject instance.
49     *
50     * @param subject object to which the policies are attached. Must not be {@code null}.
51     * @param policy first policy attached to the subject. Must not be {@code null}.
52     *
53     * @throws IllegalArgumentException in case any of the arguments is {@code null}.
54     */
55    public PolicySubject(Object subject, Policy policy) throws IllegalArgumentException {
56        if (subject == null || policy == null) {
57            throw LOGGER.logSevereException(new IllegalArgumentException(LocalizationMessages.WSP_0021_SUBJECT_AND_POLICY_PARAM_MUST_NOT_BE_NULL(subject, policy)));
58        }
59
60        this.subject = subject;
61        this.attach(policy);
62    }
63
64    /**
65     * Constructs a policy subject instance.
66     *
67     * @param subject object to which the policies are attached. Must not be {@code null}.
68     * @param policies first policy attached to the subject. Must not be {@code null}.
69     *
70     * @throws IllegalArgumentException in case any of the arguments is {@code null} or
71     *         in case {@code policies} argument represents empty collection.
72     */
73    public PolicySubject(Object subject, Collection<Policy> policies) throws IllegalArgumentException {
74        if (subject == null || policies == null) {
75            throw LOGGER.logSevereException(new IllegalArgumentException(LocalizationMessages.WSP_0062_INPUT_PARAMS_MUST_NOT_BE_NULL()));
76        }
77
78        if (policies.isEmpty()) {
79            throw LOGGER.logSevereException(new IllegalArgumentException(LocalizationMessages.WSP_0064_INITIAL_POLICY_COLLECTION_MUST_NOT_BE_EMPTY()));
80        }
81
82        this.subject = subject;
83        this.policies.addAll(policies);
84    }
85
86    /**
87     * Attaches another Policy instance to the policy subject.
88     *
89     * @param policy new policy instance to be attached to this subject
90     *
91     * @throws IllegalArgumentException in case {@code policy} argument is {@code null}.
92     */
93    public void attach(final Policy policy) {
94        if (policy == null) {
95            throw LOGGER.logSevereException(new IllegalArgumentException(LocalizationMessages.WSP_0038_POLICY_TO_ATTACH_MUST_NOT_BE_NULL()));
96        }
97        this.policies.add(policy);
98    }
99
100    /**
101     * Returns the effective policy of the subject, i.e. all policies of the subject
102     * merged together.
103     *
104     * @return effective policy of the subject
105     */
106    public Policy getEffectivePolicy(final PolicyMerger merger) throws PolicyException {
107        return merger.merge(policies);
108    }
109
110    /**
111     * A unique identifier of the subject
112     *
113     * Subjects may not always be uniquely identifiable. Also, once the subject is
114     * assigned to a scope, its identity may not matter anymore. Therefore this
115     * may be null.
116     */
117    public Object getSubject() {
118        return this.subject;
119    }
120
121    /**
122     * An {@code Object.toString()} method override.
123     */
124    @Override
125    public String toString() {
126        return toString(0, new StringBuffer()).toString();
127    }
128
129    /**
130     * A helper method that appends indented string representation of this instance to the input string buffer.
131     *
132     * @param indentLevel indentation level to be used.
133     * @param buffer buffer to be used for appending string representation of this instance
134     * @return modified buffer containing new string representation of the instance
135     */
136    StringBuffer toString(final int indentLevel, final StringBuffer buffer) {
137        final String indent = PolicyUtils.Text.createIndent(indentLevel);
138        final String innerIndent = PolicyUtils.Text.createIndent(indentLevel + 1);
139
140        buffer.append(indent).append("policy subject {").append(PolicyUtils.Text.NEW_LINE);
141        buffer.append(innerIndent).append("subject = '").append(subject).append('\'').append(PolicyUtils.Text.NEW_LINE);
142        for (Policy policy : policies) {
143            policy.toString(indentLevel + 1, buffer).append(PolicyUtils.Text.NEW_LINE);
144        }
145        buffer.append(indent).append('}');
146
147        return buffer;
148    }
149}
150