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

org.apache.brooklyn.api.location.LocationRegistry 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.location;

import java.util.List;
import java.util.Map;
import java.util.NoSuchElementException;

import javax.annotation.Nullable;

import org.apache.brooklyn.api.entity.Entity;
import org.apache.brooklyn.api.entity.EntitySpec;
import org.apache.brooklyn.api.mgmt.LocationManager;
import org.apache.brooklyn.util.guava.Maybe;

/**
 * The registry of the sorts of locations that brooklyn knows about. Given a
 * {@LocationDefinition} or a {@link String} representation of a spec, this can
 * be used to create a {@link Location} instance.
 */
public interface LocationRegistry {

    /** map of ID (possibly randomly generated) to the definition (spec, name, id, and props; 
     * where spec is the spec as defined, for instance possibly another named:xxx location) */
    public Map getDefinedLocations();
    
    /** returns a LocationDefinition given its ID (usually a random string), or null if none */
    public LocationDefinition getDefinedLocationById(String id);
    
    /** returns a LocationDefinition given its name (e.g. for named locations, supply the bit after the "named:" prefix), 
     * or null if none */
    public LocationDefinition getDefinedLocationByName(String name);

    /** adds or updates the given defined location */
    public void updateDefinedLocation(LocationDefinition l);

    /** removes the defined location from the registry (applications running there are unaffected) */
    public void removeDefinedLocation(String id);

    /** Returns a fully populated (config etc) location from the given definition, with optional add'l flags.
     * the location will be managed by default, unless the manage parameter is false, 
     * or the manage parameter is null and the CREATE_UNMANAGED flag is set.
     * 

* The manage parameter is {@link Boolean} so that null can be used to say rely on anything in the flags. * * @since 0.7.0, but beta and likely to change as the semantics of this class are tuned * @deprecated since 0.9.0 use {@link #getLocationSpec(String, Map)} or {@link #getLocationManaged(String, Map)} */ @SuppressWarnings("rawtypes") @Deprecated public Maybe resolve(LocationDefinition ld, Boolean manage, Map locationFlags); /** As {@link #resolve(LocationDefinition, Boolean, Map), with the location managed, and no additional flags, * unwrapping the result (throwing if not resolvable) * @deprecated since 0.9.0 use {@link #getLocationSpec(LocationDefinition, Map)} and then manage it as needed*/ @Deprecated public Location resolve(LocationDefinition l); /** Returns a location created from the given spec, which might correspond to a definition, or created on-the-fly. * Optional flags can be passed through to underlying the location. * @since 0.7.0, but beta and likely to change as the semantics of this class are tuned * @deprecated since 0.9.0 use {@link #getLocationSpec(String, Map)} or {@link #getLocationManaged(String, Map)} */ @SuppressWarnings("rawtypes") @Deprecated public Maybe resolve(String spec, Boolean manage, Map locationFlags); /** See {@link #resolve(String, Boolean, Map)}; asks for the location to be managed, and supplies no additional flags, * and unwraps the result (throwing if the spec cannot be resolve). * @deprecated since 0.9.0 use {@link #getLocationSpec(String)} or {@link #getLocationManaged(String)} */ @Deprecated public Location resolve(String spec); /** Returns true/false depending whether spec seems like a valid location, * that is it has a chance of being resolved (depending on the spec) but NOT guaranteed, * as it is not passed to the spec; * see {@link #resolve(String, Boolean, Map)} which has stronger guarantees * @deprecated since 0.7.0, not really needed, and semantics are weak; use {@link #resolve(String, Boolean, Map)} */ @Deprecated public boolean canMaybeResolve(String spec); /** As {@link #resolve(String, Boolean, Map)}, but unwrapped * @throws NoSuchElementException if the spec cannot be resolved * @deprecated since 0.9.0 use {@link #getLocationSpec(String, Map)} and then manage it as needed*/ @SuppressWarnings("rawtypes") @Deprecated public Location resolve(String spec, @Nullable Map locationFlags); /** * As {@link #getLocationManaged(String)} but takes collections (of strings or locations) *

* Expects a collection of elements being individual location spec strings or locations, * and returns a list of resolved (newly created and managed) locations. *

* From 0.7.0 this no longer flattens lists (nested lists are disallowed) * or parses comma-separated elements (they are resolved as-is) * @deprecated since 0.9.0 use {@link #getListOfLocationsManaged(Object)} */ @Deprecated public List resolve(Iterable spec); /** Takes a string, interpreted as a comma-separated (or JSON style, when you need internal double quotes or commas) list; * or a list, passed to {@link #resolve(Iterable)}; or null/empty (empty list), * and returns a list of resolved (created and managed) locations * @deprecated since 0.9.0 use {@link #getListOfLocationsManaged(Object)} */ @Deprecated public List resolveList(Object specList); /** Create a {@link LocationSpec} representing the given spec string such as a named location * or using a resolver prefix such as jclouds:aws-ec2. * This can then be inspected, assigned to an {@link EntitySpec}, * or passed to {@link LocationManager#createLocation(LocationSpec)} to create directly. * (For that last case, common in tests, see {@link #getLocationManaged(String)}.) */ public Maybe> getLocationSpec(String spec); /** As {@link #getLocationSpec(String)} but also setting the given flags configured on the resulting spec. */ public Maybe> getLocationSpec(String spec, Map locationFlags); /** As {@link #getLocationSpec(String)} where the caller has a {@link LocationDefinition}. */ public Maybe> getLocationSpec(LocationDefinition ld); /** As {@link #getLocationSpec(String,Map)} where the caller has a {@link LocationDefinition}. */ public Maybe> getLocationSpec(LocationDefinition ld, Map locationFlags); /** A combination of {@link #getLocationSpec(String)} then {@link LocationManager#createLocation(LocationSpec)}, * mainly for use in tests or specialised situations where a managed location is needed directly. * The caller is responsible for ensuring that the resulting {@link Location} * is cleaned up, ie removed from management via {@link LocationManager#unmanage(Location)} directly or linking it to * an {@link Entity} or another {@link Location} which will unmanage it. */ public Location getLocationManaged(String spec); /** As {@link #getLocationManaged(String)} applying the config as per {@link #getLocationSpec(String, Map)}. */ public Location getLocationManaged(String spec, Map locationFlags); /** Takes a string, interpreted as a comma-separated (or JSON style, when you need internal double quotes or commas) list; * or a list of strings, or null (giving the empty list) and returns a list of managed locations. * Note that lists of lists are not permitted. *

* The caller is responsible for ensuring these get cleaned up, as described at {@link #getLocationManaged(String)}. */ public List getListOfLocationsManaged(Object specList); @SuppressWarnings("rawtypes") public Map getProperties(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy