BasicLocationRegistry (Apache Brooklyn)

java.lang.Object
- org.apache.brooklyn.core.location.BasicLocationRegistry

All Implemented Interfaces:

LocationRegistry
```
public class BasicLocationRegistry
extends java.lang.Object
implements LocationRegistry
```
See LocationRegistry for general description.
TODO The relationship between the catalog and the location registry is a bit messy. For all existing code, the location registry is the definitive way to resolve locations.
Any location item added to the catalog must therefore be registered here. Whenever an item is added to the catalog, it will automatically call updateDefinedLocation(RegisteredType). Similarly, when a location is deleted from the catalog it will call #removeDefinedLocation(RegisteredType).
However, the location item in the catalog has an unparsed blob of YAML, which contains important things like the type and the config of the location. This is only parsed when BrooklynCatalog.createSpec(CatalogItem) is called. We therefore jump through some hoops to wire together the catalog and the registry.
To add a location to the catalog, and then to resolve a location that is in the catalog, it goes through the following steps:
1. Call BrooklynCatalog.addItems(String)
  1. This automatically calls updateDefinedLocation(RegisteredType)
  2. A LocationDefinition is creating, using as its id the RegisteredType.getSymbolicName(). The definition's spec is brooklyn.catalog:<symbolicName>:<version>,
2. A blueprint can reference the catalog item using its symbolic name, such as the YAML location: my-new-location. (this feels similar to the "named locations").
  1. This automatically calls getLocationManaged(String).
  2. The LocationDefinition is found by lookig up this name.
  3. The LocationDefiniton.getSpec() is retrieved; the right LocationResolver is found for it.
  4. This uses the CatalogLocationResolver, because the spec starts with brooklyn.catalog:.
  5. This resolver extracts from the spec the :, and looks up the location item using the BrooklynTypeRegistry.
  6. It then creates a LocationSpec by calling BrooklynTypeRegistry#createSpec(RegisteredType).
    1. This first tries to use the type (that is in the YAML) as a simple Java class.
    2. If that fails, it will resolve the type using resolve(String, Boolean, Map), which returns an actual location object.
    3. It extracts from that location object the appropriate metadata to create a LocationSpec, returns the spec and discards the location object.
  7. The resolver creates the Location from the LocationSpec
TODO we should change the registry to be a pass-through facade on top of the catalog, and shift to preferring catalog access mechanisms. this brings it in line with how we do other things; also this does not understand versions. to do this we will need to:
update the catalog on addition, setting a plan (ensuring serialization); in case of a definition CHANGED in brooklyn.properties give an error if it means the plan has changed (user could then remove from brooklyn.properties, if persistence on, or apply the update in the catalog; ie similar semantics to defining an initial catalog via the CLI)
find and return the RegisteredType from the type-registry/catalog here
Once done, update the UI use /v1/catalog/locations instead of /v1/locations (currently the latter is the only way to list locations known in the LocationRegistry ie those from brookln.properties.)

Field Summary

Fields
Modifier and Type Field and Description

static org.slf4j.Logger log

Fields
Modifier and Type	Field and Description
`static org.slf4j.Logger`	`log`

Constructor Summary

Constructors
Constructor and Description

BasicLocationRegistry(ManagementContext mgmt)

Constructors
Constructor and Description
`BasicLocationRegistry(ManagementContext mgmt)`

Method Summary

Methods
Modifier and Type	Method and Description
`static void`	`addNamedLocationLocalhost(ManagementContext mgmt)`
`boolean`	`canMaybeResolve(java.lang.String spec)` Deprecated.
`static java.util.List<java.lang.String>`	`expandCommaSeparateLocations(java.lang.String locations)` Splits a comma-separated list of locations (names or specs) into an explicit list.
`LocationDefinition`	`getDefinedLocationById(java.lang.String id)` returns a LocationDefinition given its ID (usually a random string), or null if none
`LocationDefinition`	`getDefinedLocationByName(java.lang.String name)` returns a LocationDefinition given its name (e.g.
`java.util.Map<java.lang.String,LocationDefinition>`	`getDefinedLocations()` 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)
`java.util.List<Location>`	`getListOfLocationsManaged(java.lang.Object l)` 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.
`Location`	`getLocationManaged(java.lang.String spec)` A combination of `LocationRegistry.getLocationSpec(String)` then `LocationManager.createLocation(LocationSpec)`, mainly for use in tests or specialised situations where a managed location is needed directly.
`Location`	`getLocationManaged(java.lang.String spec, java.util.Map locationFlags)` As `LocationRegistry.getLocationManaged(String)` applying the config as per `LocationRegistry.getLocationSpec(String, Map)`.
`Maybe<LocationSpec<? extends Location>>`	`getLocationSpec(LocationDefinition ld)` As `LocationRegistry.getLocationSpec(String)` where the caller has a `LocationDefinition`.
`Maybe<LocationSpec<? extends Location>>`	`getLocationSpec(LocationDefinition ld, java.util.Map locationFlags)` As `LocationRegistry.getLocationSpec(String,Map)` where the caller has a `LocationDefinition`.
`Maybe<LocationSpec<? extends Location>>`	`getLocationSpec(java.lang.String spec)` Create a `LocationSpec` representing the given spec string such as a named location or using a resolver prefix such as jclouds:aws-ec2.
`Maybe<LocationSpec<? extends Location>>`	`getLocationSpec(java.lang.String spec, java.util.Map locationFlags)` As `LocationRegistry.getLocationSpec(String)` but also setting the given flags configured on the resulting spec.
`java.util.Map`	`getProperties()`
`static boolean`	`isResolverPrefixForSpec(LocationResolver resolver, java.lang.String spec, boolean argumentRequired)` providers default impl for `LocationResolver.accepts(String, LocationRegistry)`
`void`	`putProperties(java.util.Map<java.lang.String,?> vals)`
`boolean`	`registerResolver(LocationResolver r)` Registers the given resolver, invoking `LocationResolver.init(ManagementContext)` on the argument and returning true, unless the argument indicates false for `LocationResolver.EnableableLocationResolver#isEnabled()`
`void`	`removeDefinedLocation(CatalogItem<Location,LocationSpec<?>> item)`
`void`	`removeDefinedLocation(java.lang.String id)` removes the defined location from the registry (applications running there are unaffected)
`java.util.List<Location>`	`resolve(java.lang.Iterable<?> spec)` Deprecated.
`Location`	`resolve(LocationDefinition ld)` Deprecated.
`Maybe<Location>`	`resolve(LocationDefinition ld, java.lang.Boolean manage, java.util.Map locationFlags)` Deprecated.
`Location`	`resolve(java.lang.String spec)` Deprecated.
`Maybe<Location>`	`resolve(java.lang.String spec, java.lang.Boolean manage, java.util.Map locationFlags)` Deprecated.
`Location`	`resolve(java.lang.String spec, java.util.Map locationFlags)` Deprecated.
`java.util.List<Location>`	`resolveList(java.lang.Object l)` Deprecated.
`void`	`updateDefinedLocation(CatalogItem<Location,LocationSpec<?>> item)` Converts the given item from the catalog into a LocationDefinition, and adds it to the registry (overwriting anything already registered with the id `CatalogItem.getCatalogItemId()`.
`void`	`updateDefinedLocation(LocationDefinition l)` adds or updates the given defined location
`void`	`updateDefinedLocation(RegisteredType item)` Converts the given item from the catalog into a LocationDefinition, and adds it to the registry (overwriting anything already registered with the id `RegisteredType.getId()`.
`void`	`updateDefinedLocations()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - log
```
public static final org.slf4j.Logger log
```
- Constructor Detail
  - BasicLocationRegistry
```
public BasicLocationRegistry(ManagementContext mgmt)
```
- Method Detail
  - expandCommaSeparateLocations
```
public static java.util.List<java.lang.String> expandCommaSeparateLocations(java.lang.String locations)
```
    Splits a comma-separated list of locations (names or specs) into an explicit list. The splitting is very careful to handle commas embedded within specs, to split correctly.
  - registerResolver
```
public boolean registerResolver(LocationResolver r)
```
    Registers the given resolver, invoking LocationResolver.init(ManagementContext) on the argument and returning true, unless the argument indicates false for LocationResolver.EnableableLocationResolver#isEnabled()
  - getDefinedLocations
```
public java.util.Map<java.lang.String,LocationDefinition> getDefinedLocations()
```
    Description copied from 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)
    
    Specified by:
    
    getDefinedLocations in interface LocationRegistry
  - getDefinedLocationById
```
public LocationDefinition getDefinedLocationById(java.lang.String id)
```
    Description copied from interface: LocationRegistry
    
    returns a LocationDefinition given its ID (usually a random string), or null if none
    
    Specified by:
    
    getDefinedLocationById in interface LocationRegistry
  - getDefinedLocationByName
```
public LocationDefinition getDefinedLocationByName(java.lang.String name)
```
    Description copied from interface: LocationRegistry
    
    returns a LocationDefinition given its name (e.g. for named locations, supply the bit after the "named:" prefix), or null if none
    
    Specified by:
    
    getDefinedLocationByName in interface LocationRegistry
  - updateDefinedLocation
```
public void updateDefinedLocation(LocationDefinition l)
```
    Description copied from interface: LocationRegistry
    
    adds or updates the given defined location
    
    Specified by:
    
    updateDefinedLocation in interface LocationRegistry
  - updateDefinedLocation
```
public void updateDefinedLocation(CatalogItem<Location,LocationSpec<?>> item)
```
    Converts the given item from the catalog into a LocationDefinition, and adds it to the registry (overwriting anything already registered with the id CatalogItem.getCatalogItemId().
  - updateDefinedLocation
```
public void updateDefinedLocation(RegisteredType item)
```
    Converts the given item from the catalog into a LocationDefinition, and adds it to the registry (overwriting anything already registered with the id RegisteredType.getId().
  - removeDefinedLocation
```
public void removeDefinedLocation(CatalogItem<Location,LocationSpec<?>> item)
```
  - removeDefinedLocation
```
public void removeDefinedLocation(java.lang.String id)
```
    Description copied from interface: LocationRegistry
    
    removes the defined location from the registry (applications running there are unaffected)
    
    Specified by:
    
    removeDefinedLocation in interface LocationRegistry
  - updateDefinedLocations
```
public void updateDefinedLocations()
```
  - canMaybeResolve
```
@Deprecated
public boolean canMaybeResolve(java.lang.String spec)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    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 LocationRegistry.resolve(String, Boolean, Map) which has stronger guarantees
    
    Specified by:
    
    canMaybeResolve in interface LocationRegistry
  - resolve
```
@Deprecated
public final Location resolve(java.lang.String spec)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    See LocationRegistry.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).
    
    Specified by:
    
    resolve in interface LocationRegistry
  - resolve
```
@Deprecated
public Maybe<Location> resolve(java.lang.String spec,
                                 java.lang.Boolean manage,
                                 java.util.Map locationFlags)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    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.
    
    Specified by:
    
    resolve in interface LocationRegistry
  - getLocationManaged
```
public Location getLocationManaged(java.lang.String spec)
```
    Description copied from interface: LocationRegistry
    
    A combination of LocationRegistry.getLocationSpec(String) then 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 Location is cleaned up, ie removed from management via LocationManager.unmanage(Location) directly or linking it to an Entity or another Location which will unmanage it.
    
    Specified by:
    
    getLocationManaged in interface LocationRegistry
  - getLocationManaged
```
public final Location getLocationManaged(java.lang.String spec,
                          java.util.Map locationFlags)
```
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.getLocationManaged(String) applying the config as per LocationRegistry.getLocationSpec(String, Map).
    
    Specified by:
    
    getLocationManaged in interface LocationRegistry
  - getLocationSpec
```
public Maybe<LocationSpec<? extends Location>> getLocationSpec(LocationDefinition ld)
```
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.getLocationSpec(String) where the caller has a LocationDefinition.
    
    Specified by:
    
    getLocationSpec in interface LocationRegistry
  - getLocationSpec
```
public Maybe<LocationSpec<? extends Location>> getLocationSpec(LocationDefinition ld,
                                                      java.util.Map locationFlags)
```
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.getLocationSpec(String,Map) where the caller has a LocationDefinition.
    
    Specified by:
    
    getLocationSpec in interface LocationRegistry
  - getLocationSpec
```
public Maybe<LocationSpec<? extends Location>> getLocationSpec(java.lang.String spec)
```
    Description copied from interface: LocationRegistry
    
    Create a 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 EntitySpec, or passed to LocationManager.createLocation(LocationSpec) to create directly. (For that last case, common in tests, see LocationRegistry.getLocationManaged(String).)
    
    Specified by:
    
    getLocationSpec in interface LocationRegistry
  - getLocationSpec
```
public Maybe<LocationSpec<? extends Location>> getLocationSpec(java.lang.String spec,
                                                      java.util.Map locationFlags)
```
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.getLocationSpec(String) but also setting the given flags configured on the resulting spec.
    
    Specified by:
    
    getLocationSpec in interface LocationRegistry
  - resolve
```
@Deprecated
public final Location resolve(java.lang.String spec,
                          java.util.Map locationFlags)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.resolve(String, Boolean, Map), but unwrapped
    
    Specified by:
    
    resolve in interface LocationRegistry
  - isResolverPrefixForSpec
```
public static boolean isResolverPrefixForSpec(LocationResolver resolver,
                              java.lang.String spec,
                              boolean argumentRequired)
```
    providers default impl for LocationResolver.accepts(String, LocationRegistry)
  - resolve
```
@Deprecated
public java.util.List<Location> resolve(java.lang.Iterable<?> spec)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.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)
    
    Specified by:
    
    resolve in interface LocationRegistry
  - resolveList
```
@Deprecated
public java.util.List<Location> resolveList(java.lang.Object l)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    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 LocationRegistry.resolve(Iterable); or null/empty (empty list), and returns a list of resolved (created and managed) locations
    
    Specified by:
    
    resolveList in interface LocationRegistry
  - getListOfLocationsManaged
```
public java.util.List<Location> getListOfLocationsManaged(java.lang.Object l)
```
    Description copied from interface: LocationRegistry
    
    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 LocationRegistry.getLocationManaged(String).
    
    Specified by:
    
    getListOfLocationsManaged in interface LocationRegistry
  - resolve
```
@Deprecated
public Location resolve(LocationDefinition ld)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    As {@link #resolve(LocationDefinition, Boolean, Map), with the location managed, and no additional flags, unwrapping the result (throwing if not resolvable)
    
    Specified by:
    
    resolve in interface LocationRegistry
  - resolve
```
@Deprecated
public Maybe<Location> resolve(LocationDefinition ld,
                                 java.lang.Boolean manage,
                                 java.util.Map locationFlags)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    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 Boolean so that null can be used to say rely on anything in the flags.
    
    Specified by:
    
    resolve in interface LocationRegistry
  - getProperties
```
public java.util.Map getProperties()
```
    Specified by:
    
    getProperties in interface LocationRegistry
  - putProperties
```
public void putProperties(java.util.Map<java.lang.String,?> vals)
```
  - addNamedLocationLocalhost
```
public static void addNamedLocationLocalhost(ManagementContext mgmt)
```

Class BasicLocationRegistry

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

Constructor Detail

BasicLocationRegistry

Method Detail

expandCommaSeparateLocations

registerResolver

getDefinedLocations

getDefinedLocationById

getDefinedLocationByName

updateDefinedLocation

updateDefinedLocation

updateDefinedLocation

removeDefinedLocation

removeDefinedLocation

updateDefinedLocations

canMaybeResolve

resolve

resolve

getLocationManaged

getLocationManaged

getLocationSpec

getLocationSpec

getLocationSpec

getLocationSpec

resolve

isResolverPrefixForSpec

resolve

resolveList

getListOfLocationsManaged

resolve

resolve

getProperties

putProperties

addNamedLocationLocalhost