org.apache.brooklyn.api.objs.BrooklynObject Maven / Gradle / Ivy

Go to download
/*
 * 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.objs;

import java.util.List;
import java.util.Map;
import java.util.Set;

import javax.annotation.Nonnull;

import org.apache.brooklyn.api.entity.Entity;
import org.apache.brooklyn.api.entity.Group;
import org.apache.brooklyn.api.mgmt.SubscriptionContext;
import org.apache.brooklyn.api.mgmt.SubscriptionHandle;
import org.apache.brooklyn.api.mgmt.SubscriptionManager;
import org.apache.brooklyn.api.relations.RelationshipType;
import org.apache.brooklyn.api.sensor.Sensor;
import org.apache.brooklyn.api.sensor.SensorEventListener;

import com.google.common.annotations.Beta;
import com.google.common.collect.ImmutableMap;

/**
 * Super-type of entity, location, policy and enricher.
 */
public interface BrooklynObject extends Identifiable, Configurable {
    
    /**
     * A display name; recommended to be a concise single-line description.
     */
    String getDisplayName();

    /**
     * The catalog item ID this object was loaded from.
     * 
     * This can be used to understand the appropriate classloading context,
     * such as for versioning purposes, as well as meta-information such as 
     * branding (maybe you can even get an icon) and 
     * potentially things like resource lifecycle (if a software version is being sunsetted).
     * 

     * In some cases this may be set heuristically from context and so may not be accurate.
     * Callers can set an explicit catalog item ID if inferencing is not correct.
     * 

     * This should conform to OSGi specs for symbolic_name:version
     * but weaker semantics are usually allowed so long as neither segment contains a : or whitespace.
     */
    String getCatalogItemId();

    /**
     * An immutable list of ids of catalog items that this item depends on in some way,
     * with the item that directly defines it implicit, but other items it references explicit.
     * Wrapping items are first in the list (i.e. wrapping items precede wrapped items),
     * so for example, if the catalog is:
     * 
     *     items:
     *     - id: X
     *     - id: Y
     *       item: X
     *     - id: Z
     *       item: Y
     * 
     * the spec for Z will have getCatalogId() of Z and getCatalogItemIdSearchPath() of Y, X.
     * (The self catalog ID is implicit at the head of the search path.)
     */
    List getCatalogItemIdSearchPath();
    
    /** 
     * Tags are arbitrary objects which can be attached to an entity for subsequent reference.
     * They must not be null (as {@link ImmutableMap} may be used under the covers; also there is little point!);
     * and they should be amenable to our persistence (on-disk serialization) and our JSON serialization in the REST API.
     */
    TagSupport tags();

    /**
     * Subscriptions are the mechanism for receiving notifications of sensor-events (e.g. attribute-changed) from 
     * other entities.
     */
    SubscriptionSupport subscriptions();

    /**
     * Relations specify a typed, directed connection between two entities.
     * Generic type is overridden in sub-interfaces.
     */
    public RelationSupport relations();
    
    public interface TagSupport {
        /**
         * @return An immutable copy of the set of tags on this entity. 
         * Note {@link #containsTag(Object)} will be more efficient,
         * and {@link #addTag(Object)} and {@link #removeTag(Object)} will not work on the returned set.
         */
        @Nonnull Set