Documentation ¶
Overview ¶
Package config provides functionality for working with configuration files and command line arguments to a Granitic application.
Grantic uses JSON files to store component definitions (declarations of, and relationships between, components to run in the IoC container) and configuration (variables used by IoC components that may vary between environments and settings for Grantic's built-in facilities). A defintion of the use and syntax of these files are outside of the scope of a GoDoc page, but are described in detail at http://granitic.io/1.0/ref/components and http://granitic.io/1.0/ref/config
This package defines functionality for loading a JSON file (from a filesystem or via HTTP) and merging multiple files into a single view. This is a key concept in Granitic.
Given a folder of configuration files called conf:
conf/x.json conf/sub/a.json conf/sub/b.json
starting a Grantic application with:
-c http://example.com/base.json,conf,http://example.com/myinstance.json
The following will take place. Firstly the files would be expanded into a flat list of paths/URIs
http://example.com/base.json conf/sub/a.json conf/sub/b.json conf/x.json http://example.com/myinstance.json
The the files will be merged together from left, using the the first file as a base. In this example, http://example.com/base.json and conf/sub/a.json will be merged together, then result of that merge will be merged with conf/sub/b.json and so on.
For named fields (in a JSON object/map), the process of merging is fairly obvious. When merging files A and B, a field that is defined in both files will have the value of the field used in file B in the merged output. For example,
a.json { "database": { "host": "localhost", "port": 3306, "flags": ["a", "b", "c"] } }
and
b.json { "database": { "host": "remotehost", "flags": ["d"] } }
woud merge to:
{ "database": { "host": "remotehost", "port": 3306, "flags": ["d"] } }
The merging of configuration files occurs exactly above, but when component definition files are merged, arrays are joined, not overwritten. For example:
{ "methods": ["GET"] }
merged with;
{ "methods": ["POST"] }
would result in:
{ "methods": ["GET", "POST"] }
Another core concept used by the types in this package is a config path. This is the absolute path to field in the eventual merged configuration file with a dot-delimited notation. E.g "database.host".
Index ¶
- Constants
- func ExpandToFilesAndURLs(paths []string) ([]string, error)
- func FileListFromPath(path string) ([]string, error)
- func FindConfigFilesInDir(dirPath string) ([]string, error)
- func GraniticHome() string
- func JsonType(value interface{}) int
- type ConfigAccessor
- func (c *ConfigAccessor) Array(path string) ([]interface{}, error)
- func (c *ConfigAccessor) BoolVal(path string) (bool, error)
- func (c *ConfigAccessor) Float64Val(path string) (float64, error)
- func (c *ConfigAccessor) Flush()
- func (c *ConfigAccessor) IntVal(path string) (int, error)
- func (c *ConfigAccessor) ObjectVal(path string) (map[string]interface{}, error)
- func (c *ConfigAccessor) PathExists(path string) bool
- func (ca *ConfigAccessor) Populate(path string, target interface{}) error
- func (ca *ConfigAccessor) SetField(fieldName string, path string, target interface{}) error
- func (c *ConfigAccessor) StringVal(path string) (string, error)
- func (c *ConfigAccessor) Value(path string) interface{}
- type ContentParser
- type InitialSettings
- type JsonContentParser
- type JsonMerger
Constants ¶
const ( Unset = -2 JsonUnknown = -1 JsonString = 1 JsonArray = 2 JsonMap = 3 JsonBool = 4 )
Used by code that needs to know what type of JSON data structure resides at a particular path before operating on it.
const JsonPathSeparator string = "."
The character used to delimit paths to config values.
Variables ¶
This section is empty.
Functions ¶
func ExpandToFilesAndURLs ¶
ExpandToFilesAndURLs takes a slice that may be a mixture of URLs, file paths and directory paths and returns a list of URLs and file paths, recursively expanding any non-empty directories into a list of files. Returns an error if there is a problem traversing directories of if any of the supplied file paths does not exist.
func FileListFromPath ¶
FileListFromPath takes a string that could represent a path to a directory or a path to a file and returns a list of file paths. If the path is to directory, any files in that directory are included in the result. Any sub-directories are recursively entered.
func FindConfigFilesInDir ¶
FindConfigFilesInDir finds all files with a .json extension in the supplied directory path, recursively checking sub-directories. Note that each directory's contents are examined and added to the list of files lexicographically, so any files in a sub-directory 'b' would appear in the resulting list of files before 'c.json'
func GraniticHome ¶
func GraniticHome() string
Returns the value of the OS environment variable GRANITIC_HOME. This is expected to be the path (without a trailing /) where Grantic has been installed (e.g. /home/youruser/go/src/github.com/graniticio/granitic). This is required so that configuration files for built-in facilities can be loaded from the resource sub-directory of the Granitic installation.
Types ¶
type ConfigAccessor ¶
type ConfigAccessor struct { // The merged JSON configuration in object form. JsonData map[string]interface{} // Logger used by Granitic framework components. Automatically injected. FrameworkLogger logging.Logger }
A ConfigAccessor provides access to a merged view of configuration files during the initialisation and configuration of the Granitic IoC container.
func (*ConfigAccessor) Array ¶
func (c *ConfigAccessor) Array(path string) ([]interface{}, error)
Array returns the value of an array of JSON obects at the supplied path. Caution should be used when calling this method as behaviour is undefined for JSON arrays of JSON types other than object.
func (*ConfigAccessor) BoolVal ¶
func (c *ConfigAccessor) BoolVal(path string) (bool, error)
BoolVal returns the bool value of the JSON bool at the supplied path. An error will be returned if the value is not a JSON bool. Note this method only suports the JSON definition of bools (true, false) not the Go definition (true, false, 1, 0 etc).
func (*ConfigAccessor) Float64Val ¶
func (c *ConfigAccessor) Float64Val(path string) (float64, error)
IntVal returns the float64 value of the JSON number at the supplied path. An error will be returned if the value is not a JSON number.
func (*ConfigAccessor) Flush ¶
func (c *ConfigAccessor) Flush()
Flush removes internal references to the (potentially very large) merged JSON data so the associated memory can be recovered during the next garbage collection.
func (*ConfigAccessor) IntVal ¶
func (c *ConfigAccessor) IntVal(path string) (int, error)
IntVal returns the int value of the JSON number at the supplied path. JSON numbers are internally represented by Go as a float64, so no error will be returned, but data might be lost if the JSON number does not actually represent an int. An error will be returned if the value is not a JSON number or cannot be converted to an int.
func (*ConfigAccessor) ObjectVal ¶
func (c *ConfigAccessor) ObjectVal(path string) (map[string]interface{}, error)
ObjectVal returns a map representing a JSON object or nil if the path does not exist of points to a null JSON value. An error is returned if the value cannot be interpreted as a JSON object.
func (*ConfigAccessor) PathExists ¶
func (c *ConfigAccessor) PathExists(path string) bool
PathExists check to see whether the supplied dot-delimited path exists in the configuration and points to a non-null JSON value.
func (*ConfigAccessor) Populate ¶
func (ca *ConfigAccessor) Populate(path string, target interface{}) error
Populate sets the fields on the supplied target object using the JSON data at the supplied path. This is acheived using Go's json.Marshal to convert the data back into text JSON and then json.Unmarshal to unmarshal back into the target.
func (*ConfigAccessor) SetField ¶
func (ca *ConfigAccessor) SetField(fieldName string, path string, target interface{}) error
SetField takes a target Go interface and uses the data a the supplied path to populated the named field on the target. The target must be a pointer to a struct. The field must be a string, bool, int, float63, string[interface{}] map or a slice of one of those types. An eror will be returned if the target field, is missing, not settable or incompatiable with the JSON value at the supplied path.
func (*ConfigAccessor) StringVal ¶
func (c *ConfigAccessor) StringVal(path string) (string, error)
ObjectVal returns the string value of the JSON string at the supplied path. Does not convert other types to a string, so will return an error if the value is not a JSON string.
func (*ConfigAccessor) Value ¶
func (c *ConfigAccessor) Value(path string) interface{}
Value returns the JSON value at the supplied path or nil if the path does not exist of points to a null JSON value.
type ContentParser ¶ added in v1.3.0
type ContentParser interface { ParseInto(data []byte, target interface{}) error Extensions() []string ContentTypes() []string }
A ContentParser can take a []byte of some structured file type (e.g. YAML, JSON() and convert into a map[string]interface{} representation
type InitialSettings ¶
type InitialSettings struct { // The level at which messages from Granitic components used before configuration files can be loaded (the initiator, // logger, IoC container, JSON merger etc.) will be logged. As soon as configuration has been loaded, this value will // be discarded in favour of LogLevels defined in that configuration. FrameworkLogLevel logging.LogLevel // Files, directories and URLs from which JSON configuration should be loaded and merged. Configuration []string // The time at which the application was started (to allow accurate timing of the IoC container start process). StartTime time.Time // An (optional) unique identifier for this instance of a Granitic application. InstanceId string // A base 64 serialised version of Granitic's built-in configuration files BuiltInConfig *string // Additional parsers to support config files in a format other than JSON ConfigParsers []ContentParser // Exit immediately after container has successfully started DryRun bool }
InitialSettings contains settings that are needed by Granitic before configuration files can be loaded and parsed. See package granitic for more information on how this is used when starting a Granitic application with command line arguments or supplying an instance of this struct programmatically.
func InitialSettingsFromEnvironment ¶
func InitialSettingsFromEnvironment() *InitialSettings
InitialSettingsFromEnvironment builds an InitialSettings and populates it with defaults or the values of command line arguments if available.
type JsonContentParser ¶ added in v1.3.0
type JsonContentParser struct { }
func (*JsonContentParser) ContentTypes ¶ added in v1.3.0
func (jcp *JsonContentParser) ContentTypes() []string
func (*JsonContentParser) Extensions ¶ added in v1.3.0
func (jcp *JsonContentParser) Extensions() []string
func (*JsonContentParser) ParseInto ¶ added in v1.3.0
func (jcp *JsonContentParser) ParseInto(data []byte, target interface{}) error
type JsonMerger ¶ added in v1.1.0
type JsonMerger struct { // Logger used by Granitic framework components. Automatically injected. Logger logging.Logger // True if arrays should be joined when merging; false if the entire conetnts of the array should be overwritten. MergeArrays bool DefaultParser ContentParser // contains filtered or unexported fields }
A JsonMerger can merge a sequence of JSON configuration files (from a filesystem or HTTP URL) into a single view of configuration that will be used to configure Grantic's facilities and the user's IoC components. See the top of this page for a brief explanation of how merging works.
func NewJsonMergerWithDirectLogging ¶ added in v1.3.0
func NewJsonMergerWithDirectLogging(l logging.Logger, cp ContentParser) *JsonMerger
func NewJsonMergerWithManagedLogging ¶ added in v1.3.0
func NewJsonMergerWithManagedLogging(flm *logging.ComponentLoggerManager, cp ContentParser) *JsonMerger
NewJsonMerger creates a JsonMerger with a Logger
func (*JsonMerger) LoadAndMergeConfig ¶ added in v1.1.0
func (jm *JsonMerger) LoadAndMergeConfig(files []string) (map[string]interface{}, error)
LoadAndMergeConfig takes a list of file paths or URIs to JSON files and merges them into a single in-memory object representation. See the top of this page for a brief explanation of how merging works. Returns an error if a remote URI returned a 4xx or 5xx response code, a file or folder could not be accessed or if two files could not be merged dued to JSON parsing errors.
func (*JsonMerger) LoadAndMergeConfigWithBase ¶ added in v1.2.1
func (jm *JsonMerger) LoadAndMergeConfigWithBase(config map[string]interface{}, files []string) (map[string]interface{}, error)
func (*JsonMerger) RegisterContentParser ¶ added in v1.3.0
func (jm *JsonMerger) RegisterContentParser(cp ContentParser)