org.apache.brooklyn.api.location.LocationRegistry Maven / Gradle / Ivy
/*
* 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();
}