PermissionCollection.java revision fd6bb3510c2f94d636f3572dcf5f7f4dcd1a2726 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.security;
19
20import java.io.Serializable;
21import java.util.ArrayList;
22import java.util.Enumeration;
23import java.util.List;
24
25/**
26 * {@code PermissionCollection} is the common base class for all collections
27 * that provide a convenient method for determining whether or not a given
28 * permission is implied by any of the permissions present in this collection.
29 * <p>
30 * A {@code PermissionCollection} is typically created by using the
31 * {@link Permission#newPermissionCollection()} factory method. If the mentioned
32 * method returns {@code null}, then a {@code PermissionCollection} of any type
33 * can be used. If a collection is returned, it must be used for holding several
34 * permissions of the particular type.
35 * <p>
36 * Subclasses must be implemented thread save.
37 */
38public abstract class PermissionCollection implements Serializable {
39
40    private static final long serialVersionUID = -6727011328946861783L;
41
42    private boolean readOnly; // = false;
43
44    /**
45     * Adds the specified {@code Permission} to this collection.
46     *
47     * @param permission
48     *            the {@code Permission} to add.
49     * @throws IllegalStateException
50     *             if the collection is read only.
51     */
52    public abstract void add(Permission permission);
53
54    /**
55     * Returns an enumeration over all {@link Permission}s encapsulated by this
56     * {@code PermissionCollection}.
57     *
58     * @return an enumeration over all {@link Permission}s.
59     */
60    public abstract Enumeration<Permission> elements();
61
62    /**
63     * Indicates whether the specified permission is implied by this {@code
64     * PermissionCollection}.
65     *
66     * @param permission
67     *            the permission to check.
68     * @return {@code true} if the given permission is implied by the
69     *         permissions in this collection, {@code false} otherwise.
70     */
71    public abstract boolean implies(Permission permission);
72
73    /**
74     * Indicates whether new permissions can be added to this {@code
75     * PermissionCollection}.
76     *
77     * @return {@code true} if the receiver is read only, {@code false} if new
78     *         elements can still be added to this {@code PermissionCollection}.
79     */
80    public boolean isReadOnly() {
81        return readOnly;
82    }
83
84    /**
85     * Marks this {@code PermissionCollection} as read only, so that no new
86     * permissions can be added to it.
87     */
88    public void setReadOnly() {
89        readOnly = true;
90    }
91
92    /**
93     * Returns a string containing a concise, human-readable description of this
94     * {@code PermissionCollection}.
95     *
96     * @return a printable representation for this {@code PermissionCollection}.
97     */
98    @Override
99    public String toString() {
100        List<String> elist = new ArrayList<String>(100);
101        Enumeration<Permission> elenum = elements();
102        String superStr = super.toString();
103        int totalLength = superStr.length() + 5;
104        if (elenum != null) {
105            while (elenum.hasMoreElements()) {
106                String el = elenum.nextElement().toString();
107                totalLength += el.length();
108                elist.add(el);
109            }
110        }
111        int esize = elist.size();
112        totalLength += esize * 4;
113        StringBuilder result = new StringBuilder(totalLength).append(superStr)
114            .append(" (");
115        for (int i = 0; i < esize; i++) {
116            result.append("\n ").append(elist.get(i).toString());
117        }
118        return result.append("\n)\n").toString();
119    }
120}
121