# Class GazetteerFactory

Object
AbstractFactory
GazetteerFactory

All Implemented Interfaces:
  `Factory`

public class GazetteerFactory extends AbstractFactory
A factory of reference systems by identifiers implemented by the SIS library. Current implementation can instantiate shared instances of `MilitaryGridReferenceSystem` and `GeohashReferenceSystem`. MGRS and Geohash are not really "gazetteers", but we handle them in this class for having a unique framework for referencing by identifiers. Real gazetteers may be added in a future version.

Since:
  1.3

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GazetteerFactory()`
  Creates a new factory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ReferencingByIdentifiers`
  `forName(String name)`
  Returns a shared instance of the reference system identified by the given name.
  `Optional<ReferencingByIdentifiers>`
  `forNameIfKnown(String name)`
  Optionally returns a shared instance of the reference system identified by the given name.
  `Set<String>`
  `getSupportedNames()`
  Returns the name of referencing systems known to this factory.

  ### Methods inherited from class AbstractFactory

  `getVendor, toString`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### GazetteerFactory

    public GazetteerFactory()
    Creates a new factory.

- ## Method Details

  - ### getSupportedNames

    public Set<String> getSupportedNames()
    Returns the name of referencing systems known to this factory.
    Returns:
      names of known reference systems.

  - ### forName

    public ReferencingByIdentifiers forName(String name) throws GazetteerException
    Returns a shared instance of the reference system identified by the given name. The current implementation recognizes the following names (case-sensitive):

    Supported reference systems by identifiers
    Name | Reference system class
    --- | ---
    MGRS | `MilitaryGridReferenceSystem`
    Geohash | `GeohashReferenceSystem`

    Parameters:
      `name` - name of the reference system to obtain.
    Returns:
      shared instance of the reference system for the given name.
    Throws:
      `GazetteerException` - if the reference system cannot be obtained.

  - ### forNameIfKnown

    public Optional<ReferencingByIdentifiers> forNameIfKnown(String name) throws GazetteerException
    Optionally returns a shared instance of the reference system identified by the given name. This method performs the same work as `forName(String)` but without throwing an exception if the given name is unknown.
    Parameters:
      `name` - name of the reference system to obtain.
    Returns:
      shared instance of the reference system for the given name.
    Throws:
      `GazetteerException` - if the reference system cannot be obtained.