• Home
• io.helidon.config
• helidon-config
• 2.0.0-M2
• source code
• package-info.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

io.helidon.config.package-info Maven / Gradle / Ivy

/*
 * Copyright (c) 2017, 2020 Oracle and/or its affiliates.
 *
 * Licensed 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.
 */

/**
 * Provides interfaces and classes for loading and working with immutable, tree-structured
 * configuration data.
 *
 * 
Loading a Configuration
 *
 * The program loads a configuration from either the default sources (using {@link io.helidon.config.Config#create}) or
 * from specified {@link io.helidon.config.spi.ConfigSource}s
 * (using {@link io.helidon.config.Config.Builder Config.Builder}).
 * 

 * The default sources include all of the following, in order:
 * 

 * 
environment variables
 * 
Java system properties
 * 
the first of the following (if any) on the classpath:
 * 

 * 
application.yaml
 * 
application.conf (HOCON format)
 * 
application.json
 * 
application.properties
 * 
 * 
 * 
 * The config implementation supports sources in the above formats. The program can add
 * support for other formats by implementing {@link io.helidon.config.spi.ConfigParser}.
 * 

 * See {@link io.helidon.config.Config} for further information.
 *
 * 
Using a Configuration Tree
 *
 * This overview summarizes how a program can use loaded configuration.
 * For full details see the {@link io.helidon.config.Config} class.
 * 

 * Once loaded, configuration information is available to the program as {@code Config}
 * nodes in a tree. Each node has:
 * 

 * 
a name,
 * 
a {@link io.helidon.config.Config.Key} representing
 * the full path from the root to the node, and 
 * 
some content. 
 * 
 * The {@link io.helidon.config.Config#type()} method
 * returns an enum value {@link io.helidon.config.Config.Type} that tells how the
 * program should interpret the content of the node.
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
Config Node Types
Type
Meaning
Useful {@code Config} Methods
VALUE
value node with an optional direct {@code String} value
LIST
list of indexed nodes with an optional "direct" value
{@link io.helidon.config.Config#asList(java.lang.Class)},
 * {@link io.helidon.config.Config#asNodeList()}
OBJECT
object node with, possibly, child nodes and an optional "direct" value
{@link io.helidon.config.Config#asNodeList()}
 *
 * 
Configuration Values and Types
 * While each node's direct value is accessible as
 * an {@code Optional}, the program can also
 * have the node convert its {@code String} value to a typed {@link io.helidon.config.ConfigValue} using methods such as
 * {@link io.helidon.config.Config#asString()}, {@link io.helidon.config.Config#asLong()} etc.
 * 

 * The program can provide its own {@link io.helidon.config.spi.ConfigMapperProvider} implementations
 * to deal with more complicated value mapping needs. See also {@link io.helidon.config.Config.Builder#addStringMapper}
 * and {@link io.helidon.config.Config.Builder#addMapper(java.lang.Class, java.util.function.Function)}.
 *
 * 
Navigation
 *
 * The program can retrieve a node's child
 * nodes as a {@code List}.
 * 

 * The program can navigate directly to a given subnode using the
 * {@link io.helidon.config.Config#get} method and passing the dotted path to the subnode.
 * 

 * The {@link io.helidon.config.Config#traverse} methods return a stream of nodes
 * in depth-first order.
 *
 * 
Bulk Retrieval of Values
 *
 * The program can retrieve a {@code Map} of dotted names to {@code String} values
 * for a node's entire subtree using {@link io.helidon.config.Config#asMap}.
 *
 * 
Monitoring Changes
 *
 * The program can react to configuration changes by passing a listener
 * to {@link io.helidon.config.Config#onChange(java.util.function.Consumer)}.
 *
 * 
Converting Configuration to Java Types
 * The {@link io.helidon.config.Config} class provides many methods for converting config
 * {@code String} values to Java primitives and simple Java types, as well as
 * mapping parts of the config tree to {@code List}s and {@code Map}s.
 * 

 * The application can convert config data to arbitrary types using the
 * {@link io.helidon.config.Config#as(java.lang.Class)} and {@link io.helidon.config.Config#as(java.util.function.Function)}
 * methods, and can provide its own conversions to handle
 * custom types by implementing a mapping function and registering it
 * with a {@code Config.Builder} using the {@link io.helidon.config.Config.Builder#addMapper} method.
 * 

 * If the {@code Config.as} method finds no matching registered mapper it will throw
 * a {@link io.helidon.config.ConfigMappingException}.
 * Support for automated mapping to types is available in module config-beans.
 *
 * @see io.helidon.config.spi Configuration SPI
 */
package io.helidon.config;