BasicLocationRegistry (Apache Brooklyn)

java.lang.Object
- brooklyn.location.basic.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(CatalogItem). Similarly, when a location is deleted from the catalog it will call removeDefinedLocation(CatalogItem).
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(CatalogItem)
  2. A LocationDefinition is creating, using as its id the CatalogItem.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 resolve(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 catalog item using BrooklynCatalog.getCatalogItem(String, String).
  6. It then creates a LocationSpec by calling BrooklynCatalog.createSpec(CatalogItem).
    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
There is no concept of a location version in this registry. The version in the catalog is generally ignored.

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
`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.Map`	`getProperties()`
`static boolean`	`isResolverPrefixForSpec(LocationResolver resolver, java.lang.String spec, boolean argumentRequired)` providers default impl for RegistryLocationResolver.accepts
`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)` As `LocationRegistry.resolve(String)` but takes collections (of strings or locations)
`Location`	`resolve(LocationDefinition ld)` As {@link #resolve(LocationDefinition, Boolean, Map), with the location managed, and no additional flags, unwrapping the result (throwing if not resolvable)
`Maybe<Location>`	`resolve(LocationDefinition ld, java.lang.Boolean manage, java.util.Map locationFlags)` Returns a fully populated (config etc) location from the given definition, with optional add'l flags.
`Location`	`resolve(LocationDefinition ld, java.util.Map<?,?> flags)` Deprecated.
`Location`	`resolve(java.lang.String spec)` 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)
`Maybe<Location>`	`resolve(java.lang.String spec, boolean manage)` Deprecated.
`Maybe<Location>`	`resolve(java.lang.String spec, java.lang.Boolean manage, java.util.Map locationFlags)` Returns a location created from the given spec, which might correspond to a definition, or created on-the-fly.
`Location`	`resolve(java.lang.String spec, java.util.Map locationFlags)` As `LocationRegistry.resolve(String, Boolean, Map)`, but unwrapped
`Location`	`resolveForPeeking(LocationDefinition ld)` Deprecated.
`Location`	`resolveIfPossible(java.lang.String spec)` Deprecated.
`java.util.List<Location>`	`resolveList(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, passed to `LocationRegistry.resolve(Iterable)`; or null/empty (empty list), and returns a list of resolved (created and managed) locations
`Location`	`resolveLocationDefinition(LocationDefinition ld, java.util.Map locationFlags, java.lang.String optionalName)` Deprecated. since 0.7.0 not used (and optionalName was ignored anyway)
`static void`	`setupLocationRegistryForTesting(ManagementContext mgmt)`
`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`	`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().
  - 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
```
public final Location resolve(java.lang.String spec)
```
    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
  - resolveIfPossible
```
@Deprecated
public final Location resolveIfPossible(java.lang.String spec)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    as LocationRegistry.resolve(String) but returning null (never throwing)
    
    Specified by:
    
    resolveIfPossible in interface LocationRegistry
  - resolve
```
@Deprecated
public final Maybe<Location> resolve(java.lang.String spec,
                                 boolean manage)
```
    Deprecated.
  - resolve
```
public Maybe<Location> resolve(java.lang.String spec,
                      java.lang.Boolean manage,
                      java.util.Map locationFlags)
```
    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
  - resolve
```
public final Location resolve(java.lang.String spec,
               java.util.Map locationFlags)
```
    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 RegistryLocationResolver.accepts
  - resolve
```
public java.util.List<Location> resolve(java.lang.Iterable<?> spec)
```
    Description copied from interface: LocationRegistry
    
    As LocationRegistry.resolve(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
```
public java.util.List<Location> resolveList(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, 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
  - resolve
```
public Location resolve(LocationDefinition ld)
```
    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
  - resolveForPeeking
```
@Deprecated
public Location resolveForPeeking(LocationDefinition ld)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    efficiently returns for inspection only a fully populated (config etc) location from the given definition; the value might be unmanaged so it is not meant for any use other than inspection, but callers should prefer this when they don't wish to create a new location which will be managed in perpetuity!
    
    Specified by:
    
    resolveForPeeking in interface LocationRegistry
  - resolve
```
@Deprecated
public Location resolve(LocationDefinition ld,
                          java.util.Map<?,?> flags)
```
    Deprecated.
    
    Description copied from interface: LocationRegistry
    
    returns fully populated (config etc) location from the given definition, with overrides;
    
    Specified by:
    
    resolve in interface LocationRegistry
  - resolveLocationDefinition
```
@Deprecated
public Location resolveLocationDefinition(LocationDefinition ld,
                                            java.util.Map locationFlags,
                                            java.lang.String optionalName)
```
    Deprecated. since 0.7.0 not used (and optionalName was ignored anyway)
  - resolve
```
public Maybe<Location> resolve(LocationDefinition ld,
                      java.lang.Boolean manage,
                      java.util.Map locationFlags)
```
    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
  - setupLocationRegistryForTesting
```
public static void setupLocationRegistryForTesting(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

removeDefinedLocation

removeDefinedLocation

updateDefinedLocations

canMaybeResolve

resolve

resolveIfPossible

resolve

resolve

resolve

isResolverPrefixForSpec

resolve

resolveList

resolve

resolveForPeeking

resolve

resolveLocationDefinition

resolve

getProperties

setupLocationRegistryForTesting