TAMAYA-178: Fix menu structure
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/ede865e4 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/ede865e4 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/ede865e4 Branch: refs/heads/master Commit: ede865e4d7623bd7622e1f6c03312a8ee0e11752 Parents: c74a60d Author: Phil Ottlinger <pottlin...@apache.org> Authored: Sun Dec 18 23:26:49 2016 +0100 Committer: Phil Ottlinger <pottlin...@apache.org> Committed: Sun Dec 18 23:26:49 2016 +0100 ---------------------------------------------------------------------- content/api.adoc | 687 ------------------- content/blog/2016/fourth-post.adoc | 17 +- content/blog/2016/third-post.adoc | 16 +- content/community.adoc | 123 ---- content/core.adoc | 214 ------ content/development/community.adoc | 123 ++++ content/development/source.adoc | 23 + content/documentation/api.adoc | 687 +++++++++++++++++++ content/documentation/core.adoc | 214 ++++++ content/documentation/extensions.adoc | 62 ++ .../documentation/extensions/mod_builder.adoc | 83 +++ content/documentation/extensions/mod_camel.adoc | 129 ++++ content/documentation/extensions/mod_cdi.adoc | 217 ++++++ .../extensions/mod_classloader_support.adoc | 75 ++ .../extensions/mod_collections.adoc | 232 +++++++ .../documentation/extensions/mod_consul.adoc | 59 ++ .../extensions/mod_environment.adoc | 42 ++ content/documentation/extensions/mod_etcd.adoc | 189 +++++ .../documentation/extensions/mod_events.adoc | 278 ++++++++ .../documentation/extensions/mod_filter.adoc | 119 ++++ .../documentation/extensions/mod_formats.adoc | 206 ++++++ .../documentation/extensions/mod_functions.adoc | 108 +++ .../documentation/extensions/mod_injection.adoc | 430 ++++++++++++ .../documentation/extensions/mod_jodatime.adoc | 48 ++ content/documentation/extensions/mod_json.adoc | 62 ++ .../extensions/mod_management.adoc | 92 +++ .../extensions/mod_metamodel-staged.adoc | 58 ++ content/documentation/extensions/mod_model.adoc | 451 ++++++++++++ .../extensions/mod_mutable_config.adoc | 267 +++++++ .../documentation/extensions/mod_optional.adoc | 54 ++ content/documentation/extensions/mod_osgi.adoc | 116 ++++ .../documentation/extensions/mod_remote.adoc | 115 ++++ .../documentation/extensions/mod_resolver.adoc | 126 ++++ .../documentation/extensions/mod_resources.adoc | 155 +++++ .../documentation/extensions/mod_server.adoc | 366 ++++++++++ .../extensions/mod_spi-support.adoc | 57 ++ .../documentation/extensions/mod_spring.adoc | 134 ++++ content/documentation/extensions/mod_yaml.adoc | 112 +++ content/documentation/quickstart.adoc | 189 +++++ content/documentation/usecases.adoc | 488 +++++++++++++ content/extensions.adoc | 62 -- content/extensions/mod_builder.adoc | 83 --- content/extensions/mod_camel.adoc | 129 ---- content/extensions/mod_cdi.adoc | 217 ------ content/extensions/mod_classloader_support.adoc | 75 -- content/extensions/mod_collections.adoc | 232 ------- content/extensions/mod_consul.adoc | 59 -- content/extensions/mod_environment.adoc | 42 -- content/extensions/mod_etcd.adoc | 189 ----- content/extensions/mod_events.adoc | 278 -------- content/extensions/mod_filter.adoc | 119 ---- content/extensions/mod_formats.adoc | 206 ------ content/extensions/mod_functions.adoc | 108 --- content/extensions/mod_injection.adoc | 430 ------------ content/extensions/mod_jodatime.adoc | 48 -- content/extensions/mod_json.adoc | 62 -- content/extensions/mod_management.adoc | 92 --- content/extensions/mod_metamodel-staged.adoc | 58 -- content/extensions/mod_model.adoc | 451 ------------ content/extensions/mod_mutable_config.adoc | 267 ------- content/extensions/mod_optional.adoc | 54 -- content/extensions/mod_osgi.adoc | 116 ---- content/extensions/mod_remote.adoc | 115 ---- content/extensions/mod_resolver.adoc | 126 ---- content/extensions/mod_resources.adoc | 155 ----- content/extensions/mod_server.adoc | 366 ---------- content/extensions/mod_spi-support.adoc | 57 -- content/extensions/mod_spring.adoc | 134 ---- content/extensions/mod_yaml.adoc | 112 --- content/quickstart.adoc | 189 ----- content/source.adoc | 23 - content/usecases.adoc | 488 ------------- templates/menu.thyme | 32 +- 73 files changed, 6205 insertions(+), 6192 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/api.adoc ---------------------------------------------------------------------- diff --git a/content/api.adoc b/content/api.adoc deleted file mode 100644 index 1dd1d41..0000000 --- a/content/api.adoc +++ /dev/null @@ -1,687 +0,0 @@ -:jbake-type: page -:jbake-status: published - -[[CoreDesign]] -== Apache Tamaya: API - -Though Tamaya is a very powerful and flexible solution there are basically only a few simple core concepts required -that are the base of all the other mechanisms. As a starting point we recommend you read the corresponding -llink:HighLevelDesign.html[High Level Design Documentation] - -[[API]] -== The Tamaya API -The API provides the artifacts as described in the link:HighLevelDesign.html[High Level Design Documentation], which are: - -* A simple but complete SE *API* for accessing key/value based _Configuration_: - ** +Configuration+ hereby models configuration, the main interface of Tamaya. +Configuration+ provides - *** access to literal key/value pairs. - *** functional extension points (+with, query+) using a unary +ConfigOperator+ or - a function +ConfigurationQuery<T>+. - ** +ConfigurationProvider+ provides with +getConfiguration()+ the static entry point for accessing configuration. - ** +ConfigException+ defines a runtime exception for usage by the configuration system. - ** +TypeLiteral+ provides a possibility to type safely define the target type to be returned by a registered - +PropertyProvider+. - ** +PropertyConverter+, which defines conversion of configuration values (String) into any required target type. - -* Additionally the *SPI* provides: - ** _PropertySource:_ is the the SPI for adding configuration data. A +PropertySource+ hereby - *** is designed as a minimalistic interface that be implemented by any kind of data provider (local or remote) - *** provides single access for key/value pairs in raw format as String key/values only (+getPropertyValue+). - *** can optionally support scanning of its provided values, implementing +getProperties()+. - ** _PropertySourceProvider:_ allows to register multiple property sources dynamically, e.g. all config files found in - file system folder.. - ** +ConfigurationProviderSpi+ defines the SPI that is used as a backing bean for the +ConfigurationProvider+ - singleton. - ** +PropertyFilter+, which allows filtering of property values prior getting returned to the caller. - ** +PropertyValueCombinationPolicy+ optionally can be registered to change the way how different key/value - pairs are combined to build up the final +Configuration+ passed over to the filters registered. - ** +ConfigurationContext+, which provides a container for all the artifacts needed to build up a +Configuration+. - For example a context contains the property sources, property filters, converters and combination policy used. - Also the ordering of the property sources is defined by the context. A context instance given a - +Configuration+ can be created by calling +ConfigurationProvider.createConfiguration(context);+. - ** Similarly a +ConfigurationContext+ can be created using a +ConfigurationContextBuilder+. This builder can be - obtained calling +ConfigurationProvider.getConfigurationContextBuilder();+. - ** +ServiceContext+, which provides access to the components loaded, depending on the current runtime stack. - ** +ServiceContextManager+ provides static access to the +ServiceContext+ loaded. - -This is also reflected in the main packages of the API: - -* +org.apache.tamaya+ contains the main API abstractions used by users. -* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +ServiceContext+ - mechanism. - - - -[[APIKeyValues]] -=== Key/Value Pairs - -Basically configuration is a very generic concept. Therefore it should be modelled in a generic way. The most simple -and most commonly used approach are simple literal key/value pairs. So the core building block of {name} are key/value pairs. -You can think of a common +.properties+ file, e.g. - -[source,properties] -.A simple properties file --------------------------------------------- -a.b.c=cVal -a.b.c.1=cVal1 -a.b.c.2=cVal2 -a=aVal -a.b=abVal -a.b2=abVal --------------------------------------------- - -Now you can use +java.util.Properties+ to read this file and access the corresponding properties, e.g. - -[source,properties] --------------------------------------------- -Properties props = new Properties(); -props.readProperties(...); -String val = props.getProperty("a.b.c"); -val = props.getProperty("a.b.c.1"); -... --------------------------------------------- - - -==== Why Using Strings Only - -There are good reason to keep of non String-values as core storage representation of configuration. Mostly -there are several huge advantages: - -* Strings are simple to understand -* Strings are human readable and therefore easy to prove for correctness -* Strings can easily be used within different language, different VMs, files or network communications. -* Strings can easily be compared and manipulated -* Strings can easily be searched, indexed and cached -* It is very easy to provide Strings as configuration, which gives much flexibility for providing configuration in - production as well in testing. -* and more... - -On the other side there are also disadvantages: - -* Strings are inherently not type safe, they do not provide validation out of the box for special types, such as -numbers, dates etc. -* In many cases you want to access configuration in a typesafe way avoiding conversion to the target types explicitly - throughout your code. -* Strings are neither hierarchical nor multi-valued, so mapping hierarchical and collection structures requires some - extra efforts. - -Nevertheless most of these advantages can be mitigated easily, hereby still keeping all the benefits from above: - -* Adding type safe adapters on top of String allow to add any type easily, that can be directly mapped out of Strings. - This includes all common base types such as numbers, dates, time, but also timezones, formatting patterns and more. -* Also multi-valued, complex and collection types can be defined as a corresponding +PropertyAdapter+ knows how to - parse and create the target instance required. -* String s also can be used as references pointing to other locations and formats, where configuration is - accessible. - - -[[API Configuration]] -=== Configuration - -+Configuration+ is the main API provided by Tamaya. It allows reading of single property values or the whole -property map, but also supports type safe access: - -[source,java] -.Interface Configuration --------------------------------------------- -public interface Configuration{ - String get(String key); - String getOrDefault(String key, String value); - <T> T get(String key, Class<T> type); - <T> T getOrDefault(String key, Class<T> type, T defaultValue); - <T> T get(String key, TypeLiteral<T> type); - <T> T getOrDefault(String key, TypeLiteral<T> type, T defaultValue); - Map<String,String> getProperties(); - - // extension points - Configuration with(ConfigOperator operator); - <T> T query(ConfigQuery<T> query); - - ConfigurationContext getContext(); -} --------------------------------------------- - -Hereby - -* +<T> T get(String, Class<T>)+ provides type safe accessors for all basic wrapper types of the JDK. -* +with, query+ provide the extension points for adding additional functionality. -* +getProperties()+ provides access to all key/values, whereas entries from non scannable property sources may not - be included. -* +getOrDefault+ allows to pass default values as needed, returned if the requested value evaluated to +null+. - -The class +TypeLiteral+ is basically similar to the same class provided with CDI: - -[source,java] --------------------------------------------- -public class TypeLiteral<T> implements Serializable { - - [...] - - protected TypeLiteral(Type type) { - this.type = type; - } - - protected TypeLiteral() { } - - public static <L> TypeLiteral<L> of(Type type){...} - public static <L> TypeLiteral<L> of(Class<L> type){...} - - public final Type getType() {...} - public final Class<T> getRawType() {...} - - public static Type getGenericInterfaceTypeParameter(Class<?> clazz, Class<?> interfaceType){...} - public static Type getTypeParameter(Class<?> clazz, Class<?> interfaceType){...} - - [...] -} --------------------------------------------- - -Instances of +Configuration+ can be accessed from the +ConfigurationProvider+ singleton: - -[source,java] -.Accessing Configuration --------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); --------------------------------------------- - -Hereby the singleton is backed up by an instance of +ConfigurationProviderSpi+. - - -[[PropertyConverter]] -==== Property Type Conversion - -As illustrated in the previous section, +Configuration+ also to access non String types. Nevertheless internally -all properties are strictly modelled as pure Strings only, so non String types must be derived by converting the -configured String values into the required target type. This is achieved with the help of +PropertyConverters+: - -[source,java] --------------------------------------------- -public interface PropertyConverter<T>{ - T convert(String value, ConversionContext context); - //X TODO Collection<String> getSupportedFormats(); -} --------------------------------------------- - -The +ConversionContext+ contains additional meta-information for the accessed key, inclusing the key'a name and -additional metadata. - -+PropertyConverter+ instances can be implemented and registered by default using the +ServiceLoader+. Hereby -a configuration String value is passed to all registered converters for a type in order of their annotated +@Priority+ -value. The first non-null result of a converter is then returned as the current configuration value. - -Access to converters is provided by the current +ConfigurationContext+, which is accessible from -the +ConfigurationProvider+ singleton. - - -[[ExtensionPoints]] -=== Extension Points - -We are well aware of the fact that this library will not be able to cover all kinds of use cases. Therefore -we have added functional extension mechanisms to +Configuration+ that were used in other areas of the Java eco-system -as well: - -* +with(ConfigOperator operator)+ allows to pass arbitrary unary functions that take and return instances of - +Configuration+. Operators can be used to cover use cases such as filtering, configuration views, security - interception and more. -* +query(ConfigQuery query)+ allows to apply a function returning any kind of result based on a - +Configuration+ instance. Queries are used for accessing/deriving any kind of data based on of a +Configuration+ - instance, e.g. accessing a +Set<String>+ of root keys present. - -Both interfaces hereby are functional interfaces. Because of backward compatibility with Java 7 we did not use -+UnaryOperator+ and +Function+ from the +java.util.function+ package. Nevertheless usage is similar, so you can -use Lambdas and method references in Java 8: - -[source,java] -.Applying a +ConfigurationQuery+ using a method reference --------------------------------------------- -ConfigSecurity securityContext = ConfigurationProvider.getConfiguration().query(ConfigSecurity::targetSecurityContext); --------------------------------------------- - -NOTE: +ConfigSecurity+ is an arbitrary class only for demonstration purposes. - - -Operator calls basically look similar: - -[source,java] -.Applying a +ConfigurationOperator+ using a lambda expression: --------------------------------------------- -Configuration secured = ConfigurationProvider.getConfiguration() - .with((config) -> - config.get("foo")!=null?; - FooFilter.apply(config): - config); --------------------------------------------- - - -[[ConfigException]] -=== ConfigException - -The class +ConfigException+ models the base *runtime* exception used by the configuration system. - - -[[SPI]] -== SPI - -[[PropertySource]] -=== Interface PropertySource - -We have seen that constraining configuration aspects to simple literal key/value pairs provides us with an easy to -understand, generic, flexible, yet expendable mechanism. Looking at the Java language features a +java.util.Map<String, -String>+ and +java.util.Properties+ basically model these aspects out of the box. - -Though there are advantages in using these types as a model, there are some severe drawbacks, notably implementation -of these types is far not trivial and the collection API offers additional functionality not useful when aiming -for modelling simple property sources. - -To render an implementation of a custom +PropertySource+ as convenient as possible only the following methods were -identified to be necessary: - -[source,java] --------------------------------------------- -public interface PropertySource{ - int getOrdinal(); - String getName(); - String get(String key); - boolean isScannable(); - Map<String, String> getProperties(); -} --------------------------------------------- - -Hereby - -* +get+ looks similar to the methods on +Map+. It may return +null+ in case no such entry is available. -* +getProperties+ allows to extract all property data to a +Map<String,String>+. Other methods like +containsKey, - keySet+ as well as streaming operations then can be applied on the returned +Map+ instance. -* But not in all scenarios a property source may be scannable, e.g. when looking up keys is very inefficient, it - may not make sense to iterator over all keys to collect the corresponding properties. - This can be evaluated by calling +isScannable()+. If a +PropertySource+ is defined as non scannable accesses to - +getProperties()+ may not return all key/value pairs that would be available when accessed directly using the - +String get(String)+ method. -* +getOrdinal()+ defines the ordinal of the +PropertySource+. Property sources are managed in an ordered chain, where - property sources with higher ordinals override the ones with lower ordinals. If ordinal are the same, the natural - ordering of the fulloy qualified class names of the property source implementations are used. The reason for - not using +@Priority+ annotations is that property sources can define dynamically their ordinals, e.g. based on - a property contained with the configuration itself. -* Finally +getName()+ returns a (unique) name that identifies the +PropertySource+ within the current - +ConfigurationContext+. - -This interface can be implemented by any kind of logic. It could be a simple in memory map, a distributed configuration -provided by a data grid, a database, the JNDI tree or other resources. Or it can be a combination of multiple -property sources with additional combination/aggregation rules in place. - -+PropertySources+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current - active +ServiceContext+. - - -[[PropertySourceProvider]] -=== Interface PropertySourceProvider - -Instances of this type can be used to register multiple instances of +PropertySource+. - -[source,java] --------------------------------------------- -// @FunctionalInterface in Java 8 -public interface PropertySourceProvider{ - Collection<PropertySource> getPropertySources(); -} --------------------------------------------- - -This allows to evaluate the property sources to be read/that are available dynamically. All property sources -are read out and added to the current chain of +PropertySource+ instances within the current +ConfigurationContext+, -refer also to [[ConfigurationContext]]. - -+PropertySourceProviders+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the -current active +ServiceContext+. - - -[[PropertyFilter]] -=== Interface PropertyFilter - -Also +PropertyFilters+ can be added to a +Configuration+. They are evaluated before a +Configuration+ instance is -passed to the user. Filters can hereby used for multiple purposes, such as - -* resolving placeholders -* masking sensitive entries, such as passwords -* constraining visibility based on the current active user -* ... - -+PropertyFilters+ are by default registered using the Java +ServiceLoader+ or the mechanism provided by the current -active +ServiceContext+. Similar to property sources they are managed in an ordered filter chain, based on the -applied +@Priority+ annotations. - -A +PropertyFilter+ is defined as follows: - -[source,java] --------------------------------------------- -// Functional Interface -public interface PropertyFilter{ - String filterProperty(String value, FilterContext context); -} --------------------------------------------- - -Hereby: - -* returning +null+ will remove the key from the final result -* non null values are used as the current value of the key. Nevertheless for resolving multi-step dependencies - filter evaluation has to be continued as long as filters are still changing some of the values to be returned. - To prevent possible endless loops after a defined number of loops evaluation is stopped. -* +FilterContext+ provides additional metdata, inclusing the key accessed, which is useful in many use cases. - -This method is called each time a single entry is accessed, and for each property in a full properties result. - - -[[PropertyValueCombinationPolicy]] -==== Interface PropertyValueCombinationPolicy - -This interface can be implemented optional. It can be used to adapt the way how property key/value pairs are combined to -build up the final Configuration to be passed over to the +PropertyFilters+. The default implementation is just -overriding all values read before with the new value read. Nevertheless for collections and other use cases it is -often useful to have alternate combination policies in place, e.g. for combining values from previous sources with the -new value. Finally looking at the method's signature it may be surprising to find a +Map+ for the value. The basic -value hereby is defined by +currentValue.get(key)+. Nevertheless the +Map+ may also contain additional meta entries, -which may be considered by the policy implementation. - -[source,java] --------------------------------------------- -// FunctionalInterface -public interface PropertyValueCombinationPolicy{ - - PropertyValueCombinationPolicy DEFAULT_OVERRIDING_COLLECTOR = - new PropertyValueCombinationPolicy(){ - @Override - public Map<String,String> collect(Map<String,String> currentValue, String key, - PropertySource propertySource) { - PropertyValue value = propertySource.get(key); - return value!=null?value.getConfigEntries():currentValue; - } - }; - - String collect(Map<String,String> currentValue currentValue, String key, - PropertySource propertySource); - -} --------------------------------------------- - - -[[ConfigurationContext]] -==== The Configuration Context - -A +Configuration+ is created from a +ConfigurationContext+, which is -accessible from +Configuration.getContext()+: - -[source,java] -.Accessing the current +ConfigurationContext+ --------------------------------------------- -ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext(); --------------------------------------------- - -The +ConfigurationContext+ provides access to the internal artifacts that determine the final +Configuration+ and -also defines the ordering of the property sources, filters and converters contained: - -* +PropertySources+ registered (including the PropertySources provided from +PropertySourceProvider+ instances). -* +PropertyFilters+ registered, which filter values before they are returned to the client -* +PropertyConverter+ instances that provide conversion functionality for converting String values to any other types. -* the current +PropertyValueCombinationPolicy+ that determines how property values from different PropertySources are - combined to the final property value returned to the client. - - -[[Mutability]] -==== Changing the current Configuration Context - -A +ConfigurationContext+ is not mutable once it is created. In many cases mutability is also not needed. Nevertheless -there are use cases where the current +ConfigurationContext+ (and -consequently +Configuration+) must be adapted: - -* New configuration files where detected in a folder observed by Tamaya. -* Remote configuration, e.g. stored in a database or alternate ways has been updated and the current system must - be adapted to these changes. -* The overall configuration context is manually setup by the application logic. -* Within unit testing alternate configuration setup should be setup to meet the configuration requirements of the - tests executed. - -In such cases the +ConfigurationContext+ must be changed, meaning it must be possible: - -* to add or remove +PropertySource+ instances -* to add or remove +PropertyFilter+ instances -* to add or remove +PropertyConverter+ instances -* to redefine the current +PropertyValueCombinationPolicy+ instances. - -This can be achieved by obtaining an instance of +ConfigurationContextBuilder+. Instances of this builder can be -accessed either - -* calling +ConfigurationContext.toBuilder()+, hereby returning a builder instance preinitialized with the values from the - current +ConfigurationContext+. -* calling +ConfigurationProvider.getConfigurationContextBuilder()+. - -[source,java] -.Accessing a +ConfigurationContextBuilder+ --------------------------------------------- -ConfigurationContextBuilder preinitializedContextBuilder = ConfigurationProvider.getConfiguration().getContext().toBuilder(); -ConfigurationContextBuilder emptyContextBuilder = ConfigurationProvider.getConfigurationContextBuilder(); --------------------------------------------- - -With such a builder a new +ConfigurationContext+ can be created and then applied: - -[source,java] -.Creating and applying a new +ConfigurationContext+ --------------------------------------------- -ConfigurationContext context = ConfigurationProvider.getConfiguration().getContext() - .toBuilder(); - .addPropertySources(new MyPropertySource()) - .addPropertyFilter(new MyFilter()) - .build(); --------------------------------------------- - -Hereby the builder provides several methods for adding, removing of property sources and also operations -for programmatically change the property sourcepriorities, e.g. - -[source,java] -.Chain manipulation using +ConfigurationContextBuilder+ --------------------------------------------- -PropertySource propertySource = builder.getPropertySource("sourceId"); - -// changing the priority of a property source. The ordinal value hereby is not considered. -// Instead the position of the property source within the chain is changed. -builder.decreasePriority(propertySource); - -// Alternately a comparator expression can be passed to establish the defined ordering... -builder.sortPropertyFilters(MyFilterComparator::compare); --------------------------------------------- - -Finally if the new context is ready a new configuration can be created, or the context is applied to the -current configuration. - -[source,java] -.Creating and applying a new +ConfigurationContext+ --------------------------------------------- -ConfigurationContext context = builder.build(); - -// Creates a new matching Configuration instance -Configuration newConfig = ConfigurationProvider.createConfiguration(context); - -// Apply the new context to replace the current configuration: -ConfigurationProvider.setConfigurationContext(context); --------------------------------------------- - -Hereby +ConfigurationProvider.setConfigurationContext(context)+ can throw an +UnsupportedOperationException+. -This can be checked by calling the method +boolean ConfigurationProvider.isConfigurationContextSettable()+. - - -[[ConfigurationProviderSpi]] -==== Implementing and Managing Configuration - -One of the most important SPI in Tamaya if the +ConfigurationProviderSpi+ interface, which is backing up the -+ConfigurationProvider+ singleton. Implementing this class allows - -* to fully determine the implementation class for +Configuration+ -* to manage the current +ConfigurationContext+ in the scope and granularity required. -* to provide access to the right +Configuration/ConfigurationContext+ based on the current runtime context. -* Performing changes as set with the current +ConfigurationContextBuilder+. - -= Interface ConfigurationContextBuilder - -include::temp-properties-files-for-site/attributes.adoc[] - -[[BuilderCore]] -== Interface ConfigurationContextBuilder -=== Overview - -The Tamaya builder module provides a generic (one time) builder for creating +Configuration+ instances, -e.g. as follows: - -[source,java] ---------------------------------------------------------------- -ConfigurationBuilder builder = new ConfigurationBuilder(); -// do something -Configuration config = builder.build(); ---------------------------------------------------------------- - -Basically the builder allows to create configuration instances completely independent of the current configuration -setup. This gives you full control on the +Configuration+ setup. - - -=== Supported Functionality - -The builder allows you to add +PropertySource+ instances: - -[source,java] ----------------------------------------------------------------- -ConfigurationContextBuilder builder = ConfigurationProvider.getConfigurationContextBuilder(); -builder.addPropertySources(sourceOne, sourceTwo, sourceThree -Configuration config = ConfigurationProvider.createConfiguration(builder.build()); ----------------------------------------------------------------- - -Hereby the ordering of the propertysources is not changed, regardless of the ordinals provided -by the property sources. This allows alternate ordering policies easily being implemented because -creating a configuration based on a configuration context is already implemented and provided by the core -API. - -Similarly you can add filters: - -[source,java] ----------------------------------------------------------------- -builder.addPropertyFilters(new MyConfigFilter()); ----------------------------------------------------------------- - -...or +PropertySourceProvider+ instances: - -[source,java] ----------------------------------------------------------------- -builder.addPropertySourceProvider(new MyPropertySourceProvider()); ----------------------------------------------------------------- - - - -[[ServiceContext]] -==== The ServiceContext - -The +ServiceContext+ is also a very important SPI, which allows to define how components are loaded in Tamaya. -The +ServiceContext+ hereby defines access methods to obtain components, whereas itself it is available from the -+ServiceContextManager+ singleton: - -[source,java] -.Accessing the +ServiceContext+ --------------------------------------------- -ServiceContext serviceContext = ServiceContextManager.getServiceContext(); - -public interface ServiceContext{ - int ordinal(); - <T> T getService(Class<T> serviceType); - <T> List<T> getServices(Class<T> serviceType); -} --------------------------------------------- - -With the +ServiceContext+ a component can be accessed in two different ways: - -. access as as a single property. Hereby the registered instances (if multiple) are sorted by priority and then finally - the most significant instance is returned only. -. access all items given its type. This will return (by default) all instances loadedable from the current - runtime context, ordered by priority, hereby the most significant components added first. - - -## Examples -### Accessing Configuration - -_Configuration_ is obtained from the ConfigurationProvider singleton: - -[source,java] -.Accessing +Configuration+ --------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); --------------------------------------------- - -Many users in a SE context will probably only work with _Configuration_, since it offers all functionality -needed for basic configuration with a very lean memory and runtime footprint. In Java 7 access to the keys is -very similar to *Map<String,String>*, whereas in Java 8 additionally usage of _Optional_ is supported: - -[source,java] --------------------------------------------- -Configuration config = ConfigurationProvider.getConfiguration(); -String myKey = config.get("myKey"); // may return null -int myLimit = config.get("all.size.limit", int.class); --------------------------------------------- - - -### Environment and System Properties - -By default environment and system properties are included into the _Configuration_. So we can access the current -_PROMPT_ environment variable as follows: - -[source,java] --------------------------------------------- -String prompt = ConfigurationProvider.getConfiguration().get("PROMPT"); --------------------------------------------- - -Similary the system properties are directly applied to the _Configuration_. So if we pass the following system -property to our JVM: - -[source,java] --------------------------------------------- -java ... -Duse.my.system.answer=yes --------------------------------------------- - -we can access it as follows: - -[source,java] --------------------------------------------- -boolean useMySystem = ConfigurationProvider.getConfiguration().get("use.my.system.answer", boolean.class); --------------------------------------------- - - -### Adding a Custom Configuration - -Adding a classpath based configuration is simply as well: just implement an according _PropertySource_. With the -_tamaya-spi-support_ module you just have to perform a few steps: - -. Define a PropertySource as follows: - -[source,java] --------------------------------------------- - public class MyPropertySource extends PropertiesResourcePropertySource{ - - public MyPropertySource(){ - super(ClassLoader.getSystemClassLoader().getResource("META-INF/cfg/myconfig.properties"), DEFAULT_ORDINAL); - } - } --------------------------------------------- - -Then register +MyPropertySource+ using the +ServiceLoader+ by adding the following file: - -[source,listing] --------------------------------------------- -META-INF/services/org.apache.tamaya.spi.PropertySource --------------------------------------------- - -...containing the following line: - -[source,listing] --------------------------------------------- -com.mypackage.MyPropertySource --------------------------------------------- - - -[[APIImpl]] -== API Implementation - -The API is implemented by the Tamaya _Core_module. Refer to the link:Core.html[Core documentation] for -further details. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/blog/2016/fourth-post.adoc ---------------------------------------------------------------------- diff --git a/content/blog/2016/fourth-post.adoc b/content/blog/2016/fourth-post.adoc index f22ec22..1e395f3 100644 --- a/content/blog/2016/fourth-post.adoc +++ b/content/blog/2016/fourth-post.adoc @@ -1,6 +1,5 @@ = Fourth Post -Jonathan Bullock -2013-10-17 +2016-12-18 :jbake-type: post :jbake-status: published :jbake-tags: blog, asciidoc @@ -11,10 +10,10 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vel diam purus. * http://example.org * http://example.org[Example.org] -Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu, -mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo -ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet -ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus, -id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In -consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere -libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat. \ No newline at end of file +Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu, +mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo +ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet +ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus, +id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In +consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere +libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/blog/2016/third-post.adoc ---------------------------------------------------------------------- diff --git a/content/blog/2016/third-post.adoc b/content/blog/2016/third-post.adoc index c334f5a..46376fc 100644 --- a/content/blog/2016/third-post.adoc +++ b/content/blog/2016/third-post.adoc @@ -5,18 +5,16 @@ tags=blog, asciidoc status=published ~~~~~~ = Third Post -Jonathan Bullock -2013-10-17 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vel diam purus. Curabitur ut nisi lacus. * http://example.org * http://example.org[Example.org] -Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu, -mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo -ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet -ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus, -id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In -consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere -libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat. \ No newline at end of file +Nam id nisl quam. Donec a lorem sit amet libero pretium vulputate vel ut purus. Suspendisse leo arcu, +mattis et imperdiet luctus, pulvinar vitae mi. Quisque fermentum sollicitudin feugiat. Mauris nec leo +ligula. Vestibulum tristique odio ut risus ultricies a hendrerit quam iaculis. Duis tempor elit sit amet +ligula vehicula et iaculis sem placerat. Fusce dictum, metus at volutpat lacinia, elit massa auctor risus, +id auctor arcu enim eu augue. Donec ultrices turpis in mi imperdiet ac venenatis sapien sodales. In +consequat imperdiet nunc quis bibendum. Nulla semper, erat quis ornare tristique, lectus massa posuere +libero, ut vehicula lectus nunc ut lorem. Aliquam erat volutpat. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/community.adoc ---------------------------------------------------------------------- diff --git a/content/community.adoc b/content/community.adoc deleted file mode 100644 index ad9e1dc..0000000 --- a/content/community.adoc +++ /dev/null @@ -1,123 +0,0 @@ -:jbake-type: page -:jbake-status: published - -= Apache Tamaya: Community - -:sectnums: - -// Document properties -:twitterhandle: tamayaconf - -== Users - -If you are a new user and you would like to participate in Tamaya -(would be great!), you can have a look at the current -project documentation. Apache Tamaya currently does -not yet have a users mailing list. If you want discuss your use cases -we encourage you to mailto:dev-subscr...@tamaya.incubator.apache.org[subscribe] -to our mailto:d...@tamaya.incubator.apache.org[mailing list for developers]. -Furthermore, you can check our xref:a_mailing_lists[mail-archives]. - -Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^] -please ask on the mailing list if it's a known issue in case of a -bug or if there is an ongoing discussion in case of a feature. - -You are very welcome to follow our twitter account -https://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word -of Tamaya with tweets, blog entries,... - -== Getting Involved - -Everybody is welcome to get involved with our community. You can find general -information at https://apache.org/foundation/getinvolved.html and -https://apache.org/foundation/how-it-works.html. -The following sections provides some details about the different levels of getting involved. - -If you want to contribute to the -documentation of Apache Tamaya, please -read the instructions about the Documentation -that addresses how to contribute, render and publish it. - - -=== Contributors - -Before you get a committer you have to contribute to our effort. -E.g. you can help users, participate in discussions on the dev list, -submit patches,... . Therefore, it's essential to file -a https://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^] -or https://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^] -and send it to secretary at apache dot org (or fax it) as early as possible. - -If you would like to submit a patch through Jira, you can have a look at the -link:devguide.html[suggested Git approach]. - -The lists of current contributors and committers can be found -on the link:team-list.html[team and contributers page^]. - - -=== Committers - -Before you read this section, please ensure that you have read -the contributor section. All of you are welcome to join our development effort. -mailto:dev-subscr...@tamaya.incubator.apache.org[Subscribe] to our -mailto:d...@tamaya.incubator.apache.org[mailing list for developers] and -start contributing and help users. - -// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12 -Optionally mailto:commits-subscr...@tamaya.incubator.apache.org[subscribe] to our -mailto:commits@tamaya.incubator.apache.org[mailing list for commits]. -Furthermore, you can check our link:community.html#mailing-lists[mail-archives]. - -Further details are available at https://www.apache.org/dev/[https://www.apache.org/dev/^]. - -=== Mailing lists - -The table below lists all mailings used by the Tamaya project. - -[width="70"] -[cols="5*.<", options="header"] -|=== -| List -| Subscribe -| Unsubscribe -| Archive -| Mirrors -//-- next row -| Developer List -| mailto:dev-subscr...@tamaya.incubator.apache.org[Subscribe] -| mailto:dev-unsubscr...@tamaya.incubator.apache.org[Unsubscribe] -| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^] -| -//-- next row -| Committer List -| mailto:commits-subscr...@tamaya.incubator.apache.org[Subscribe] -| mailto:commits-unsubscr...@tamaya.incubator.apache.org[Unsubscribe] -| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^] -| -|=== - -=== JIRA - -Any kind of issue has to be filed in our -https://issues.apache.org/jira/browse/TAMAYA[issue tracker^]. -If you have any question, you can ask us -(e.g. via the mailing list for developers). - -=== Spread the word - -You are very welcome e.g. to write blog entries, mention our twitter handle - @{twitterhandle} if you tweet about the project or just follow our twitter -account https://twitter.com/{twitterhandle}[@{twitterhandle}^] - -=== IRC - -Usually discussions happen on the mailing list. Some informal discussions take -place in our IRC-Channel irc://irc.freenode.net/apache-tamaya. - ----- -// with the irssi command-line client: -$ irssi - -> /connect irc.freenode.net -> /join #apache-tamaya ----- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/core.adoc ---------------------------------------------------------------------- diff --git a/content/core.adoc b/content/core.adoc deleted file mode 100644 index 139eade..0000000 --- a/content/core.adoc +++ /dev/null @@ -1,214 +0,0 @@ -:jbake-type: page -:jbake-status: published - -[[Core]] -== Tamaya Core Implementation -=== Overview - -Tamaya Core provides an implementation of the link:API.html[Tamaya Configuration API] and adds additional functionality -and building blocks for supporting SPI implementations. - -Tamaya Core contains the following artifacts: - -* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder+ ConfigurationProviderSpi+ -* A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements component priorization based - on the +@Priority+ annotations. -* A PropertyConverterManager+ that loads and stores references to all the preconfigured +PropertyConverter+ instances -hereby providing type conversion for all important types. -* A simple default configuration setup using the current classpath and an optional staging variable. -* It collects all +PropertySource+ and +PropertySourceProvider+ instances registered with the +ServiceLoader+ and - registers them in the global +ConfigurationContext+ -* It provides a +ConfigurationContextBuilder+ implementation (class +DefaultConfigurationContextBuilder+) and allows - changing the current +ConfigurationContext+. - -The overall size of the library is very small. All required components are implemented and registered, so basically the -Core module is a complete configuration solution. Nevertheless it is also very minimalistic, but fortunately is flexible -enough to be extended/accommodated with additional features as needed, such as - -* placeholder and resolution mechanisms -* dynamic resource path lookup, e.g. with ant styled patterns -* configuration injection and configuration templates -* abstraction for reusable formats -* integration with other existing solutions -* configuration and configuration isolation targeting Java EE -* dynamic configuration and configuration updates -* Configuration management extensions -* remote configuration -* and more - -For details about the extension modules available and their functionality refer to the link:modules.html[extension user guide]. - - -[[CorePropertyConverters]] -=== Default PropertyConverters in Core - -As mentioned the Core module delivers several default +PropertyConverter+ instances out of the box. Find below the -listing of converters automatically registered with the Core module: - -[width="100%",frame="1",options="header",grid="all"] -|======= -|_Target Type_ |_Class Name_ |_Supported Formats_ -|java.math.BigDecimal |BigDecimalConverter |1.2345, 0xFF -|java.math.BigInteger |BigIntegerConverter |0xFF, 1234 -|java.ui.lang.Boolean |BooleanConverter |true, false, T, F, 1 ,0 -|java.ui.lang.Byte |ByteConverter |0xFF, MIN_VALUE, MAX_VALUE, 123 -|java.ui.lang.Character |CharConverter |0xFF, 'a', 'H', 123 -|java.ui.lang.Class |ClassConverter |<fully qualified class name> -|java.util.Currency |CurrencyConverter |CHF, 123 -|java.ui.lang.Double |DoubleConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE -|_Enums_ |EnumConverter |<Enum item name> -|java.ui.lang.Float |FloatConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY, MIN_VALUE, MAX_VALUE -|java.ui.lang.Integer |IntegerConverter |1, 0xD3, MIN_VALUE, MAX_VALUE -|LocalDate |LocalDateConverter |<Date as defined by LocalDate.parse(String) -|LocalTime |LocalTimeConverter |<Time as defined by LocalTime.parse(String) -|LocalDateTime |LocalDateTimeConverter |<LocalDateTime as defined by LocalDateTime.parse(String)> -|java.ui.lang.Long |LongConverter |1, 0xD3, MIN_VALUE, MAX_VALUE -|java.ui.lang.Number |NumberConverter |1, 0xFF, 1.2334, NaN, NEGATIVE_INFITIY, POSITIVE_INFINITY -|java.ui.lang.Short |ShortConverter |1, 0xD3, MIN_VALUE, MAX_VALUE -|java.net.URI |URIConverter |http://localhost:2020/testresource?api=true -|java.net.URL |URLConverter |http://localhost:2020/testresource?api=true -|ZoneId |ZoneIdConverter |Europe/Zurich -|======= - - -=== Registering PropertyConverters - -Additional +PropertyConverters+ can be implemented easily. It is recommended to register then using the +java.util.ServiceLoader+, -meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+ containing the fully qualified -class names of the converters to be registered (one line per each). - -Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters programmatically. - -NOTE: API Implementations can be read-only thus not allowing adding additional converters programmatically. - - -[[ComponentLoadingAndPriorization]] -=== Component Loading and Priorization - -Tamaya Core in general loads all components using the +java.util.ServiceLoader+ mechanism. This means that new components -must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing the fully qualified -implementation class names of the components to be registered (one line per each). -The +ServiceLoader+ itself does not provide any functionality for overriding or ordering of components. Tamaya -core adds this functionality by the possibility to add +@Priority+ annotations to the components registered. -By default, and if no annotation is added +0+ is used as priority. Hereby higher values preceed lower values, meaning - -* if a singleton component is accessed from the current +ServiceContext+ the component with the higher value - effectively _overrides/replaces_ any component with lower values. -* if a collection of components is obtained from the +ServiceContext+ the components are ordered in order, where the - ones with higher priority are before components with lower priority. -* if priorities match Tamaya Core additionally sorts them using the simple class name. This ensures that ordering is - still defined and predictable in almost all scenarios. - -NOTE: Sorting the property sources based on their ordinal value is only the default ordering principle applied. By implementing - your own implementation of +ConfigurationProviderSpi+ you can apply a different logic: - - -[[RegisteringPropertySources]] -=== Registering Property Sources - -PropertySources that provide configuration properties are registered as ordinary components as described in the previous -section. Nevertheless the priority is not managed based on +@Priority+ annotations, but based on an explicit -+int getOrdinal()+ method. This allows to define the ordinal/priority of a +PropertySource+ explicitly. This is useful -due to several reasons: - -* it allows to define the ordinal as part of the configuration, thus allowing new overriding property sources being - added easily. -* it allows to define the ordinal dynamically, e.g. based on the configuration location, the time of loading or - whatever may be appropriate. - - -[[CorePropertySources]] -== Configuration Setup in Core - -Tamaya Core provides a minimal configuration setting, that allows you to configure SE -applications already easily. Basically configuration is built up by default as follows: - -. Read environment properties and add them prefixed with +env.+ -. Read all files found at +META-INF/javaconfiguration.properties+ - and +META-INF/javaconfiguration.xml+ - - -=== Overview of Registered Default Property Sources and Providers - -The Tamaya Core implementation provides a couple of default +PropertySource+ implementations, which are automatically -registered. They are all in the package +org.apache.tamaya.core.propertysource+ and -+org.apache.tamaya.core.provider+: - -[width="100%",frame="1",options="header",grid="all"] -|======= -|_Type_ |_Class Name_ |_Ordinal Used_ -|META-INF/javaconfiguration.properties |JavaConfigurationProvider |0 -|META-INF/javaconfiguration.xml |JavaConfigurationProvider |0 -|Environment Properties |EnvironmentPropertySource |300 -|System Properties |SystemPropertySource |400 -|======= - - -=== Abstract Class PropertiesFilePropertySource - -The abstract class +PropertiesFilePropertySource+ can be used for implementing a +PropertySource+ based on a +URL+ -instance that points to a +.properites+ file. It requires a +URL+ to be passed on the constructor: - -[source,java] --------------------------------------------- -PropertiesFilePropertySource(URL url); --------------------------------------------- - - -==== Abstract Class PropertiesPropertySource - -The abstract class +PropertiesPropertySource+ can be used for implementing a +PropertySource+ based on a +Properties+ -instance. It requires a +PropertySource+ to be passed on the constructor: - -[source,java] --------------------------------------------- -PropertiesPropertySource(Properties properties); --------------------------------------------- - - -==== Abstract Class BasePropertySource - -The abstract class +BasePropertySource+ can be used for implementing custom +PropertySource+ classes. It requires only -one method to implemented: - -[source,java] -.Implementing a PropertySource using BasePropertySource --------------------------------------------- -public class MyPropertySource extends BasePropertySource{ - - public String getName(){ - // return a unique name for the property source, e.g. based on the underlying resource. This name also - // allows to access the property source later - } - - public Map<String, String> getProperties(){ - // Get a map with all properties provided by this property source - // If the property source is not scannable, the map returned may be empty. - // In the ladder case the +boolean isScannale()+ must be overridden, since - // by default property sources are assumed to be scannable. - } - -} --------------------------------------------- - -By default the ordinal of the property sources will be 1000, unless the key +tamaya.ordinal+ asdefined in -+PropertySource.TAMAYA_ORDINAL+ is present in the current +PropertySource+. Of course it is also possible to override -the inherited +protected void initializeOrdinal(final int defaultOrdinal)+, or directly +int getOrdinal()+. - - -[[CorePropertySourceProviders]] -=== Default PropertySourceProvider in Core - -With +org.apache.tamaya.core.provider.JavaConfigurationProvider+ there is also a default +PropertySourceProvider+ -present that loads all .properties files found at +META-INF/javaconfiguration.properties+ -and +META-INF/javaconfiguration.xml+. - - -[[Extensions]] -== Adding Extensions - -The Core module only implements the link:API.html[API]. Many users require/wish additional functionality from a -configuration system. Fortunately there are numerous extensions available that add further functionality. -Loading extensions hereby is trivial: you only are required to add the corresponding dependency to the classpath. - -For detailed information on the extensions available refer to the link:extensions.html[extensions documentation]. http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/development/community.adoc ---------------------------------------------------------------------- diff --git a/content/development/community.adoc b/content/development/community.adoc new file mode 100644 index 0000000..ad9e1dc --- /dev/null +++ b/content/development/community.adoc @@ -0,0 +1,123 @@ +:jbake-type: page +:jbake-status: published + += Apache Tamaya: Community + +:sectnums: + +// Document properties +:twitterhandle: tamayaconf + +== Users + +If you are a new user and you would like to participate in Tamaya +(would be great!), you can have a look at the current +project documentation. Apache Tamaya currently does +not yet have a users mailing list. If you want discuss your use cases +we encourage you to mailto:dev-subscr...@tamaya.incubator.apache.org[subscribe] +to our mailto:d...@tamaya.incubator.apache.org[mailing list for developers]. +Furthermore, you can check our xref:a_mailing_lists[mail-archives]. + +Before you file a ticket in our https://issues.apache.org/jira/browse/TAMAYA[Jira^] +please ask on the mailing list if it's a known issue in case of a +bug or if there is an ongoing discussion in case of a feature. + +You are very welcome to follow our twitter account +https://twitter.com/{twitterhandle}[@{twitterhandle}^] and spread the word +of Tamaya with tweets, blog entries,... + +== Getting Involved + +Everybody is welcome to get involved with our community. You can find general +information at https://apache.org/foundation/getinvolved.html and +https://apache.org/foundation/how-it-works.html. +The following sections provides some details about the different levels of getting involved. + +If you want to contribute to the +documentation of Apache Tamaya, please +read the instructions about the Documentation +that addresses how to contribute, render and publish it. + + +=== Contributors + +Before you get a committer you have to contribute to our effort. +E.g. you can help users, participate in discussions on the dev list, +submit patches,... . Therefore, it's essential to file +a https://www.apache.org/licenses/icla.txt[Individual Contributor License Agreement (ICLA)^] +or https://www.apache.org/licenses/cla-corporate.txt[Software Grant and Corporate Contributor License Agreement (CCLA)^] +and send it to secretary at apache dot org (or fax it) as early as possible. + +If you would like to submit a patch through Jira, you can have a look at the +link:devguide.html[suggested Git approach]. + +The lists of current contributors and committers can be found +on the link:team-list.html[team and contributers page^]. + + +=== Committers + +Before you read this section, please ensure that you have read +the contributor section. All of you are welcome to join our development effort. +mailto:dev-subscr...@tamaya.incubator.apache.org[Subscribe] to our +mailto:d...@tamaya.incubator.apache.org[mailing list for developers] and +start contributing and help users. + +// todo Fix the link when finishing the new homepage, Oliver B. Fischer, 2015-09-12 +Optionally mailto:commits-subscr...@tamaya.incubator.apache.org[subscribe] to our +mailto:commits@tamaya.incubator.apache.org[mailing list for commits]. +Furthermore, you can check our link:community.html#mailing-lists[mail-archives]. + +Further details are available at https://www.apache.org/dev/[https://www.apache.org/dev/^]. + +=== Mailing lists + +The table below lists all mailings used by the Tamaya project. + +[width="70"] +[cols="5*.<", options="header"] +|=== +| List +| Subscribe +| Unsubscribe +| Archive +| Mirrors +//-- next row +| Developer List +| mailto:dev-subscr...@tamaya.incubator.apache.org[Subscribe] +| mailto:dev-unsubscr...@tamaya.incubator.apache.org[Unsubscribe] +| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-dev/[Archive^] +| +//-- next row +| Committer List +| mailto:commits-subscr...@tamaya.incubator.apache.org[Subscribe] +| mailto:commits-unsubscr...@tamaya.incubator.apache.org[Unsubscribe] +| http://mail-archives.apache.org/mod_mbox/incubator-tamaya-commits/[Archive^] +| +|=== + +=== JIRA + +Any kind of issue has to be filed in our +https://issues.apache.org/jira/browse/TAMAYA[issue tracker^]. +If you have any question, you can ask us +(e.g. via the mailing list for developers). + +=== Spread the word + +You are very welcome e.g. to write blog entries, mention our twitter handle + @{twitterhandle} if you tweet about the project or just follow our twitter +account https://twitter.com/{twitterhandle}[@{twitterhandle}^] + +=== IRC + +Usually discussions happen on the mailing list. Some informal discussions take +place in our IRC-Channel irc://irc.freenode.net/apache-tamaya. + +---- +// with the irssi command-line client: +$ irssi + +> /connect irc.freenode.net +> /join #apache-tamaya +---- http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/ede865e4/content/development/source.adoc ---------------------------------------------------------------------- diff --git a/content/development/source.adoc b/content/development/source.adoc new file mode 100644 index 0000000..441bec8 --- /dev/null +++ b/content/development/source.adoc @@ -0,0 +1,23 @@ +:jbake-type: page +:jbake-status: published + +:sectnums: yes + += Apache Tamaya: Sources + +== Source Code Repositories + +The current source code can be found at: + + - http://git-wip-us.apache.org/repos/asf/incubator-tamaya.git (read-only) + - https://git-wip-us.apache.org/repos/asf/incubator-tamaya.git + +Alternatively there is also a GitHub read-only mirror at +https://github.com/apache/incubator-tamaya[https://github.com/apache/incubator-tamaya^]. + +The GitHub mirror also provides the project as downloadable zip archive. + +== Contributions + +If you like to contribute to Apache Tamaya please also refer also to our +<<devguide.adoc#contributing-workflow,section on contributing to Apache Tamaya>>.