All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.brooklyn.api.internal.AbstractBrooklynObjectSpec Maven / Gradle / Ivy

There is a newer version: 1.1.0
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.brooklyn.api.internal;

import static com.google.common.base.Preconditions.checkNotNull;

import java.io.Serializable;
import java.lang.reflect.Modifier;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.google.common.annotations.Beta;
import com.google.common.base.Objects;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableSet;
import com.google.common.collect.Iterables;
import com.google.common.collect.Maps;

import org.apache.brooklyn.api.mgmt.EntityManager;
import org.apache.brooklyn.api.mgmt.Task;
import org.apache.brooklyn.api.objs.BrooklynObject;
import org.apache.brooklyn.api.objs.SpecParameter;
import org.apache.brooklyn.config.ConfigKey;
import org.apache.brooklyn.config.ConfigKey.HasConfigKey;
import org.apache.brooklyn.util.collections.MutableSet;
import org.apache.brooklyn.util.exceptions.Exceptions;

/**
 * Defines a spec for creating a {@link BrooklynObject}.
 * 

* In addition to the contract defined by the code, * subclasses should provide a public static create(Class) * method to create an instance of the spec for the target type indicated by the argument. *

* The spec is then passed to type-specific methods, * e.g. {@link EntityManager#createEntity(org.apache.brooklyn.api.entity.EntitySpec)} * to create a managed instance of the target type. */ public abstract class AbstractBrooklynObjectSpec> implements Serializable { private static final long serialVersionUID = 3010955277740333030L; private static final Logger log = LoggerFactory.getLogger(AbstractBrooklynObjectSpec.class); private final Class type; private String displayName; private String catalogItemId; private Set tags = MutableSet.of(); private List> parameters = ImmutableList.of(); protected final Map flags = Maps.newLinkedHashMap(); protected final Map, Object> config = Maps.newLinkedHashMap(); protected AbstractBrooklynObjectSpec(Class type) { checkValidType(type); this.type = type; this.catalogItemId = ApiObjectsFactory.get().getCatalogItemIdFromContext(); } @SuppressWarnings("unchecked") protected SpecT self() { return (SpecT) this; } @Override public String toString() { return Objects.toStringHelper(this).omitNullValues() .add("type", type) .add("displayName", displayName) .toString(); } protected abstract void checkValidType(Class type); public SpecT displayName(String val) { displayName = val; return self(); } public SpecT catalogItemId(String val) { catalogItemId = val; return self(); } // TODO in many places (callers to this method) we prefer a wrapper item ID; // that is right, because the wrapper's defn will refer to the wrapped, // but we might need also to collect the item ID's so that *all* can be searched. // e.g. if R3 references R2 which references R1 any one of these might supply config keys // referencing resources or types in their local bundles. @Beta public SpecT catalogItemIdIfNotNull(String val) { if (val!=null) { catalogItemId = val; } return self(); } public SpecT tag(Object tag) { tags.add(tag); return self(); } /** adds the given tags */ public SpecT tags(Iterable tagsToAdd) { return tagsAdd(tagsToAdd); } /** adds the given tags */ public SpecT tagsAdd(Iterable tagsToAdd) { Iterables.addAll(this.tags, tagsToAdd); return self(); } /** replaces tags with the given */ public SpecT tagsReplace(Iterable tagsToReplace) { this.tags.clear(); Iterables.addAll(this.tags, tagsToReplace); return self(); } // TODO which semantics are correct? replace has been the behaviour; // add breaks tests and adds unwanted parameters, // but replacing will cause some desired parameters to be lost. // i (AH) think ideally the caller should remove any parameters which // have been defined as config keys, and then add the others; // or actually we should always add, since this is really defining the config keys, // and maybe extend the SpecParameter object to be able to advertise whether // it is a CatalogConfig or merely a config key, maybe introducing displayable, or even priority // (but note part of the reason for CatalogConfig.priority is that java reflection doesn't preserve field order) . // see also comments on the camp SpecParameterResolver. @Beta public SpecT parameters(List> parameters) { return parametersReplace(parameters); } /** adds the given parameters */ @Beta public SpecT parametersAdd(List> parameters) { // parameters follows immutable pattern, unlike the other fields Set> params = MutableSet.>copyOf(parameters); Set> current = MutableSet.>copyOf(this.parameters); current.removeAll(params); this.parameters = ImmutableList.>builder() .addAll(params) .addAll(current) .build(); return self(); } /** replaces parameters with the given */ @Beta public SpecT parametersReplace(List> parameters) { this.parameters = ImmutableList.copyOf(checkNotNull(parameters, "parameters")); return self(); } /** * @return The type (often an interface) this spec represents and which will be instantiated from it */ public Class getType() { return type; } /** * @return The display name of the object */ public final String getDisplayName() { return displayName; } public final String getCatalogItemId() { return catalogItemId; } public final Set getTags() { return ImmutableSet.copyOf(tags); } /** A list of configuration options that the entity supports. */ public final List> getParameters() { //Could be null after rebind if (parameters != null) { return ImmutableList.copyOf(parameters); } else { return ImmutableList.of(); } } // TODO Duplicates method in BasicEntityTypeRegistry and InternalEntityFactory.isNewStyleEntity protected final void checkIsNewStyleImplementation(Class implClazz) { try { implClazz.getConstructor(new Class[0]); } catch (NoSuchMethodException e) { throw new IllegalStateException("Implementation "+implClazz+" must have a no-argument constructor"); } catch (SecurityException e) { throw Exceptions.propagate(e); } if (implClazz.isInterface()) throw new IllegalStateException("Implementation "+implClazz+" is an interface, but must be a non-abstract class"); if (Modifier.isAbstract(implClazz.getModifiers())) throw new IllegalStateException("Implementation "+implClazz+" is abstract, but must be a non-abstract class"); } // TODO Duplicates method in BasicEntityTypeRegistry protected final void checkIsImplementation(Class val, Class requiredInterface) { if (!requiredInterface.isAssignableFrom(val)) throw new IllegalStateException("Implementation "+val+" does not implement "+requiredInterface.getName()); if (val.isInterface()) throw new IllegalStateException("Implementation "+val+" is an interface, but must be a non-abstract class"); if (Modifier.isAbstract(val.getModifiers())) throw new IllegalStateException("Implementation "+val+" is abstract, but must be a non-abstract class"); } protected SpecT copyFrom(SpecT otherSpec) { return displayName(otherSpec.getDisplayName()) .configure(otherSpec.getConfig()) .configure(otherSpec.getFlags()) .tags(otherSpec.getTags()) .catalogItemId(otherSpec.getCatalogItemId()) .parameters(otherSpec.getParameters()); } @Override public boolean equals(Object obj) { if (obj==null) return false; if (!obj.getClass().equals(getClass())) return false; AbstractBrooklynObjectSpec other = (AbstractBrooklynObjectSpec)obj; if (!Objects.equal(getDisplayName(), other.getDisplayName())) return false; if (!Objects.equal(getCatalogItemId(), other.getCatalogItemId())) return false; if (!Objects.equal(getType(), other.getType())) return false; if (!Objects.equal(getTags(), other.getTags())) return false; if (!Objects.equal(getConfig(), other.getConfig())) return false; if (!Objects.equal(getFlags(), other.getFlags())) return false; if (!Objects.equal(getParameters(), other.getParameters())) return false; return true; } @Override public int hashCode() { return Objects.hashCode(getCatalogItemId(), getDisplayName(), getType(), getTags()); } /** strings inserted as flags, config keys inserted as config keys; * if you want to force one or the other, create a ConfigBag and convert to the appropriate map type */ public SpecT configure(Map val) { if (val==null) { log.warn("Null supplied when configuring "+this); log.debug("Source for null supplied when configuring "+this, new Throwable("Source for null supplied when configuring "+this)); return self(); } for (Map.Entry entry: val.entrySet()) { if (entry.getKey()==null) throw new NullPointerException("Null key not permitted"); if (entry.getKey() instanceof CharSequence) flags.put(entry.getKey().toString(), entry.getValue()); else if (entry.getKey() instanceof ConfigKey) config.put((ConfigKey)entry.getKey(), entry.getValue()); else if (entry.getKey() instanceof HasConfigKey) config.put(((HasConfigKey)entry.getKey()).getConfigKey(), entry.getValue()); else { log.warn("Spec "+this+" ignoring unknown config key "+entry.getKey()); } } return self(); } public SpecT configure(CharSequence key, Object val) { flags.put(checkNotNull(key, "key").toString(), val); return self(); } public SpecT configure(ConfigKey key, V val) { config.put(checkNotNull(key, "key"), val); return self(); } public SpecT configureIfNotNull(ConfigKey key, V val) { return (val != null) ? configure(key, val) : self(); } public SpecT configure(ConfigKey key, Task val) { config.put(checkNotNull(key, "key"), val); return self(); } public SpecT configure(HasConfigKey key, V val) { config.put(checkNotNull(key, "key").getConfigKey(), val); return self(); } public SpecT configure(HasConfigKey key, Task val) { config.put(checkNotNull(key, "key").getConfigKey(), val); return self(); } public SpecT removeConfig(ConfigKey key) { config.remove(checkNotNull(key, "key")); return self(); } public SpecT removeFlag(String key) { flags.remove(checkNotNull(key, "key")); return self(); } /** Clears the config map, removing any config previously set. */ public void clearConfig() { config.clear(); } /** * @return Read-only construction flags * @see SetFromFlag declarations on the policy type */ public Map getFlags() { return Collections.unmodifiableMap(flags); } /** * @return Read-only configuration values */ public Map, Object> getConfig() { return Collections.unmodifiableMap(config); } }