|
| 1 | +/* |
| 2 | + * Copyright 2016 Google Inc. All Rights Reserved. |
| 3 | + * |
| 4 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + * you may not use this file except in compliance with the License. |
| 6 | + * You may obtain a copy of the License at |
| 7 | + * |
| 8 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | + * |
| 10 | + * Unless required by applicable law or agreed to in writing, software |
| 11 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + * See the License for the specific language governing permissions and |
| 14 | + * limitations under the License. |
| 15 | + */ |
| 16 | + |
| 17 | +package com.google.gcloud; |
| 18 | + |
| 19 | +import static com.google.common.base.Preconditions.checkArgument; |
| 20 | + |
| 21 | +import com.google.common.collect.ImmutableMap; |
| 22 | +import com.google.common.collect.ImmutableSet; |
| 23 | + |
| 24 | +import java.io.Serializable; |
| 25 | +import java.util.Arrays; |
| 26 | +import java.util.Collection; |
| 27 | +import java.util.HashMap; |
| 28 | +import java.util.HashSet; |
| 29 | +import java.util.LinkedList; |
| 30 | +import java.util.List; |
| 31 | +import java.util.Map; |
| 32 | +import java.util.Objects; |
| 33 | +import java.util.Set; |
| 34 | + |
| 35 | +/** |
| 36 | + * Base class for Identity and Access Management (IAM) policies. IAM policies are used to specify |
| 37 | + * access settings for Cloud Platform resources. A policy is a map of bindings. A binding assigns |
| 38 | + * a set of identities to a role, where the identities can be user accounts, Google groups, Google |
| 39 | + * domains, and service accounts. A role is a named list of permissions defined by IAM. |
| 40 | + * |
| 41 | + * @param <R> the data type of roles (should be serializable) |
| 42 | + * @see <a href="https://cloud.google.com/iam/reference/rest/v1/Policy">Policy</a> |
| 43 | + */ |
| 44 | +public abstract class IamPolicy<R> implements Serializable { |
| 45 | + |
| 46 | + private static final long serialVersionUID = 1114489978726897720L; |
| 47 | + |
| 48 | + private final Map<R, Set<Identity>> bindings; |
| 49 | + private final String etag; |
| 50 | + private final Integer version; |
| 51 | + |
| 52 | + /** |
| 53 | + * Builder for an IAM Policy. |
| 54 | + * |
| 55 | + * @param <R> the data type of roles |
| 56 | + * @param <B> the subclass extending this abstract builder |
| 57 | + */ |
| 58 | + public abstract static class Builder<R, B extends Builder<R, B>> { |
| 59 | + |
| 60 | + private final Map<R, Set<Identity>> bindings = new HashMap<>(); |
| 61 | + private String etag; |
| 62 | + private Integer version; |
| 63 | + |
| 64 | + /** |
| 65 | + * Constructor for IAM Policy builder. |
| 66 | + */ |
| 67 | + protected Builder() {} |
| 68 | + |
| 69 | + /** |
| 70 | + * Replaces the builder's map of bindings with the given map of bindings. |
| 71 | + * |
| 72 | + * @throws IllegalArgumentException if the provided map is null or contain any null values |
| 73 | + */ |
| 74 | + public final B bindings(Map<R, Set<Identity>> bindings) { |
| 75 | + checkArgument(bindings != null, "The provided map of bindings cannot be null."); |
| 76 | + for (Map.Entry<R, Set<Identity>> binding : bindings.entrySet()) { |
| 77 | + verifyBinding(binding.getKey(), binding.getValue()); |
| 78 | + } |
| 79 | + this.bindings.clear(); |
| 80 | + for (Map.Entry<R, Set<Identity>> binding : bindings.entrySet()) { |
| 81 | + this.bindings.put(binding.getKey(), new HashSet<Identity>(binding.getValue())); |
| 82 | + } |
| 83 | + return self(); |
| 84 | + } |
| 85 | + |
| 86 | + /** |
| 87 | + * Adds a binding to the policy. |
| 88 | + * |
| 89 | + * @throws IllegalArgumentException if the policy already contains a binding with the same role |
| 90 | + * or if the role or any identities are null |
| 91 | + */ |
| 92 | + public final B addBinding(R role, Set<Identity> identities) { |
| 93 | + verifyBinding(role, identities); |
| 94 | + checkArgument(!bindings.containsKey(role), |
| 95 | + "The policy already contains a binding with the role " + role.toString() + "."); |
| 96 | + bindings.put(role, new HashSet<Identity>(identities)); |
| 97 | + return self(); |
| 98 | + } |
| 99 | + |
| 100 | + /** |
| 101 | + * Adds a binding to the policy. |
| 102 | + * |
| 103 | + * @throws IllegalArgumentException if the policy already contains a binding with the same role |
| 104 | + * or if the role or any identities are null |
| 105 | + */ |
| 106 | + public final B addBinding(R role, Identity first, Identity... others) { |
| 107 | + HashSet<Identity> identities = new HashSet<>(); |
| 108 | + identities.add(first); |
| 109 | + identities.addAll(Arrays.asList(others)); |
| 110 | + return addBinding(role, identities); |
| 111 | + } |
| 112 | + |
| 113 | + private void verifyBinding(R role, Collection<Identity> identities) { |
| 114 | + checkArgument(role != null, "The role cannot be null."); |
| 115 | + verifyIdentities(identities); |
| 116 | + } |
| 117 | + |
| 118 | + private void verifyIdentities(Collection<Identity> identities) { |
| 119 | + checkArgument(identities != null, "A role cannot be assigned to a null set of identities."); |
| 120 | + checkArgument(!identities.contains(null), "Null identities are not permitted."); |
| 121 | + } |
| 122 | + |
| 123 | + /** |
| 124 | + * Removes the binding associated with the specified role. |
| 125 | + */ |
| 126 | + public final B removeBinding(R role) { |
| 127 | + bindings.remove(role); |
| 128 | + return self(); |
| 129 | + } |
| 130 | + |
| 131 | + /** |
| 132 | + * Adds one or more identities to an existing binding. |
| 133 | + * |
| 134 | + * @throws IllegalArgumentException if the policy doesn't contain a binding with the specified |
| 135 | + * role or any identities are null |
| 136 | + */ |
| 137 | + public final B addIdentity(R role, Identity first, Identity... others) { |
| 138 | + checkArgument(bindings.containsKey(role), |
| 139 | + "The policy doesn't contain the role " + role.toString() + "."); |
| 140 | + List<Identity> toAdd = new LinkedList<>(); |
| 141 | + toAdd.add(first); |
| 142 | + toAdd.addAll(Arrays.asList(others)); |
| 143 | + verifyIdentities(toAdd); |
| 144 | + bindings.get(role).addAll(toAdd); |
| 145 | + return self(); |
| 146 | + } |
| 147 | + |
| 148 | + /** |
| 149 | + * Removes one or more identities from an existing binding. |
| 150 | + * |
| 151 | + * @throws IllegalArgumentException if the policy doesn't contain a binding with the specified |
| 152 | + * role |
| 153 | + */ |
| 154 | + public final B removeIdentity(R role, Identity first, Identity... others) { |
| 155 | + checkArgument(bindings.containsKey(role), |
| 156 | + "The policy doesn't contain the role " + role.toString() + "."); |
| 157 | + bindings.get(role).remove(first); |
| 158 | + bindings.get(role).removeAll(Arrays.asList(others)); |
| 159 | + return self(); |
| 160 | + } |
| 161 | + |
| 162 | + /** |
| 163 | + * Sets the policy's etag. |
| 164 | + * |
| 165 | + * <p>Etags are used for optimistic concurrency control as a way to help prevent simultaneous |
| 166 | + * updates of a policy from overwriting each other. It is strongly suggested that systems make |
| 167 | + * use of the etag in the read-modify-write cycle to perform policy updates in order to avoid |
| 168 | + * race conditions. An etag is returned in the response to getIamPolicy, and systems are |
| 169 | + * expected to put that etag in the request to setIamPolicy to ensure that their change will be |
| 170 | + * applied to the same version of the policy. If no etag is provided in the call to |
| 171 | + * setIamPolicy, then the existing policy is overwritten blindly. |
| 172 | + */ |
| 173 | + protected final B etag(String etag) { |
| 174 | + this.etag = etag; |
| 175 | + return self(); |
| 176 | + } |
| 177 | + |
| 178 | + /** |
| 179 | + * Sets the version of the policy. The default version is 0, meaning only the "owner", "editor", |
| 180 | + * and "viewer" roles are permitted. If the version is 1, you may also use other roles. |
| 181 | + */ |
| 182 | + protected final B version(Integer version) { |
| 183 | + this.version = version; |
| 184 | + return self(); |
| 185 | + } |
| 186 | + |
| 187 | + @SuppressWarnings("unchecked") |
| 188 | + private B self() { |
| 189 | + return (B) this; |
| 190 | + } |
| 191 | + |
| 192 | + public abstract IamPolicy<R> build(); |
| 193 | + } |
| 194 | + |
| 195 | + protected IamPolicy(Builder<R, ? extends Builder<R, ?>> builder) { |
| 196 | + ImmutableMap.Builder<R, Set<Identity>> bindingsBuilder = ImmutableMap.builder(); |
| 197 | + for (Map.Entry<R, Set<Identity>> binding : builder.bindings.entrySet()) { |
| 198 | + bindingsBuilder.put(binding.getKey(), ImmutableSet.copyOf(binding.getValue())); |
| 199 | + } |
| 200 | + this.bindings = bindingsBuilder.build(); |
| 201 | + this.etag = builder.etag; |
| 202 | + this.version = builder.version; |
| 203 | + } |
| 204 | + |
| 205 | + /** |
| 206 | + * Returns a builder containing the properties of this IAM Policy. |
| 207 | + */ |
| 208 | + public abstract Builder<R, ? extends Builder<R, ?>> toBuilder(); |
| 209 | + |
| 210 | + /** |
| 211 | + * The map of bindings that comprises the policy. |
| 212 | + */ |
| 213 | + public Map<R, Set<Identity>> bindings() { |
| 214 | + return bindings; |
| 215 | + } |
| 216 | + |
| 217 | + /** |
| 218 | + * The policy's etag. |
| 219 | + * |
| 220 | + * <p>Etags are used for optimistic concurrency control as a way to help prevent simultaneous |
| 221 | + * updates of a policy from overwriting each other. It is strongly suggested that systems make |
| 222 | + * use of the etag in the read-modify-write cycle to perform policy updates in order to avoid |
| 223 | + * race conditions. An etag is returned in the response to getIamPolicy, and systems are |
| 224 | + * expected to put that etag in the request to setIamPolicy to ensure that their change will be |
| 225 | + * applied to the same version of the policy. If no etag is provided in the call to |
| 226 | + * setIamPolicy, then the existing policy is overwritten blindly. |
| 227 | + */ |
| 228 | + public String etag() { |
| 229 | + return etag; |
| 230 | + } |
| 231 | + |
| 232 | + /** |
| 233 | + * Sets the version of the policy. The default version is 0, meaning only the "owner", "editor", |
| 234 | + * and "viewer" roles are permitted. If the version is 1, you may also use other roles. |
| 235 | + */ |
| 236 | + public Integer version() { |
| 237 | + return version; |
| 238 | + } |
| 239 | + |
| 240 | + @Override |
| 241 | + public final int hashCode() { |
| 242 | + return Objects.hash(getClass(), bindings, etag, version); |
| 243 | + } |
| 244 | + |
| 245 | + @Override |
| 246 | + public final boolean equals(Object obj) { |
| 247 | + if (obj == null || !getClass().equals(obj.getClass())) { |
| 248 | + return false; |
| 249 | + } |
| 250 | + @SuppressWarnings("rawtypes") |
| 251 | + IamPolicy other = (IamPolicy) obj; |
| 252 | + return Objects.equals(bindings, other.bindings()) |
| 253 | + && Objects.equals(etag, other.etag()) |
| 254 | + && Objects.equals(version, other.version()); |
| 255 | + } |
| 256 | +} |
0 commit comments