All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • org.apache.brooklyn.api.objs.BrooklynObject 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.objs;

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.
     */
    String getCatalogItemId();
    
    /** 
     * 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 getTags();
        
        boolean containsTag(@Nonnull Object tag);
        
        boolean addTag(@Nonnull Object tag);
        
        boolean addTags(@Nonnull Iterable tags);
        
        boolean removeTag(@Nonnull Object tag);
    }
    
    @Beta
    public interface SubscriptionSupport {
        /**
         * Allow us to subscribe to data from a {@link Sensor} on another entity.
         * 
         * @return a subscription id which can be used to unsubscribe
         *
         * @see SubscriptionManager#subscribe(Map, Entity, Sensor, SensorEventListener)
         */
        @Beta
         SubscriptionHandle subscribe(Entity producer, Sensor sensor, SensorEventListener listener);
     
        /**
         * Allow us to subscribe to data from a {@link Sensor} on another entity.
         * 
         * @return a subscription id which can be used to unsubscribe
         *
         * @see SubscriptionManager#subscribe(Map, Entity, Sensor, SensorEventListener)
         */
        @Beta
         SubscriptionHandle subscribe(Map flags, Entity producer, Sensor sensor, SensorEventListener listener);

        /** @see SubscriptionManager#subscribeToChildren(Map, Entity, Sensor, SensorEventListener) */
        @Beta
         SubscriptionHandle subscribeToChildren(Entity parent, Sensor sensor, SensorEventListener listener);
     
        /** @see SubscriptionManager#subscribeToMembers(Group, Sensor, SensorEventListener) */
        @Beta
         SubscriptionHandle subscribeToMembers(Group group, Sensor sensor, SensorEventListener listener);

        /**
         * Unsubscribes from the given producer.
         *
         * @see SubscriptionContext#unsubscribe(SubscriptionHandle)
         */
        @Beta
        boolean unsubscribe(Entity producer);

        /**
         * Unsubscribes the given handle.
         *
         * @see SubscriptionContext#unsubscribe(SubscriptionHandle)
         */
        @Beta
        boolean unsubscribe(Entity producer, SubscriptionHandle handle);
        
        /**
         * Unsubscribes the given handle.
         * 
         * It is (currently) more efficient to also pass in the producer -
         * see {@link SubscriptionSupport#unsubscribe(Entity, SubscriptionHandle)} 
         */
        boolean unsubscribe(SubscriptionHandle handle);
    }
    
    public interface RelationSupport {
        /** Adds a relationship of the given type from this object pointing at the given target, 
         * and ensures that the inverse relationship (if there is one) is present at the target pointing back at this object. 
         */
        public  void add(RelationshipType relationship, U target);
        
        /** Removes any and all relationships of the given type from this object pointing at the given target,
         * and ensures that the inverse relationships (if there are one) are also removed. 
         */
        public  void remove(RelationshipType relationship, U target);
        
        /** @return the {@link RelationshipType}s originating from this object */
        public Set> getRelationshipTypes();
        
        /** @return the {@link BrooklynObject}s which are targets of the given {@link RelationshipType} */
        public  Set getRelations(RelationshipType relationshipType);
    }
}
    
    
    
    

    




    
    
    © 2015 - 2024 Weber Informatics LLC | Privacy Policy