content/documentation/extensions/mod_server.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: Configuration Server

toc::[]


[[Server]]
== Tamaya Configuration Server (Extension Module)

Tamaya _Server_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.


=== What functionality this module provides ?

The Tamaya _Server_ module provides support for providing scoped configuration using a http server serving JSON formatted
configuration properties.


=== Compatibility

The module is based on Java 7, so it will not run on Java 7 and beyond.


=== Installation

To benefit from configuration server support you only must add the corresponding dependency to your module:

[source, xml]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-server</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== Providing configuration using the Tamaya Built-in Configuration Server

The most simple way for providing configuration is to start the internal server:

[source, java]
-----------------------------------------------
// using context path: '/', port 8085
org.apache.tamaya.server.Server.start();

// optionally pass the root context path and/or port:
// org.apache.tamaya.server.Server.start(8088);
// org.apache.tamaya.server.Server.start("/appconf", 7787);
-----------------------------------------------

This will start a simple server instance that serves the following URL patterns:

* +GET ${CONTEXT}/config+ provides access to the full configuration tree.
* +GET ${CONTEXT}/config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated).
  E.g. +${CONTEXT}/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_.

Additionally the server module has the following options implemented, which can be passed as additional, optional
parameters:

* +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this
  setting can be explicitly controlled by passing this parameter explicitly. The value is the expected MIME type to be
  returned. By default the service supports the following types:
  ** text/html
  ** text/plain
  ** application/xml
  ** application/json


=== Using the Configuration Servlets

You can also register a servlet, e.g. as follows;

----------------------------------------------------------
<servlet>
  <servlet-name>config-servlet</servlet-name>
  <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class>
  <init-params>
    <init-param key="javax.ws.rs.Application">org.apache.tamaya.server.Server$ResourceLoader</init-param>
  </init-params>
</servlet>
----------------------------------------------------------


==== Formatting used by Default

The server module formats the configuration returned by default in the following variants:

.Formatting for +text/json+

[source, json]
-----------------------------------------------
{
  "java.vendor.url": "http://java.oracle.com/",
  "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
  "java.vm.info": "mixed mode",
  "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
  "java.vm.specification.name": "Java Virtual Machine Specification",
  "java.vm.specification.vendor": "Oracle Corporation",
  "java.vm.specification.version": "1.8",
  "java.vm.vendor": "Oracle Corporation",
  "java.vm.version": "25.45-b02",
  "sun.arch.data.model": "64",
  "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
  "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
  "sun.cpu.endian": "little",
  "sun.cpu.isalist": "amd64",
  "sun.desktop": "windows",
  "sun.io.unicode.encoding": "UnicodeLittle",
  "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
  "sun.java.launcher": "SUN_STANDARD",
  "sun.jnu.encoding": "Cp1252",
  "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
  "sun.os.patch.level": "",
  "[META]class": "org.apache.tamaya.functions.FilteredConfiguration",
  "[META]info.filter": "java.v,sun",
  "[META]info.format": "application/json",
  "[META]info.timestamp": "1441463200571",
  "[META]timestamp": "1441463200571",
  "[META]type": "Configuration"
}
-----------------------------------------------


.Formatting for +application/xml+

[source, xml]
-----------------------------------------------
<configuration>
  <entry key="java.vendor.url">http://java.oracle.com/</entry>
  <entry key="java.vendor.url.bug">http://bugreport.sun.com/bugreport/</entry>
  <entry key="java.vm.info">mixed mode</entry>
  <entry key="java.vm.name">Java HotSpot(TM) 64-Bit Server VM</entry>
  <entry key="java.vm.specification.name">Java Virtual Machine Specification</entry>
  <entry key="java.vm.specification.vendor">Oracle Corporation</entry>
  <entry key="java.vm.specification.version">1.8</entry>
  <entry key="java.vm.vendor">Oracle Corporation</entry>
  <entry key="java.vm.version">25.45-b02</entry>
  <entry key="sun.arch.data.model">64</entry>
  <entry key="sun.boot.class.path">C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes</entry>
  <entry key="sun.boot.library.path">C:\apps\jdk18\jre\bin</entry>
  <entry key="sun.cpu.endian">little</entry>
  <entry key="sun.cpu.isalist">amd64</entry>
  <entry key="sun.desktop">windows</entry>
  <entry key="sun.io.unicode.encoding">UnicodeLittle</entry>
  <entry key="sun.java.command">com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start</entry>
  <entry key="sun.java.launcher">SUN_STANDARD</entry>
  <entry key="sun.jnu.encoding">Cp1252</entry>
  <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry>
  <entry key="sun.os.patch.level"></entry>
  <entry key="_class">org.apache.tamaya.functions.FilteredConfiguration</entry>
  <entry key="_info.filter">java.v,sun</entry>
  <entry key="_info.format">application/xml</entry>
  <entry key="_info.timestamp">1441463383687</entry>
  <entry key="_timestamp">1441463383687</entry>
  <entry key="_type">Configuration</entry>
</configuration>
-----------------------------------------------


.Formatting for +text/plain+

[source, text]
-----------------------------------------------

Configuration:
  java.vendor.url: http://java.oracle.com/,
  java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
  java.vm.info: mixed mode,
  java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
  java.vm.specification.name: Java Virtual Machine Specification,
  java.vm.specification.vendor: Oracle Corporation,
  java.vm.specification.version: 1.8,
  java.vm.vendor: Oracle Corporation,
  java.vm.version: 25.45-b02,
  sun.arch.data.model: 64,
  sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
  sun.boot.library.path: C:\apps\jdk18\jre\bin,
  sun.cpu.endian: little,
  sun.cpu.isalist: amd64,
  sun.desktop: windows,
  sun.io.unicode.encoding: UnicodeLittle,
  sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
  sun.java.launcher: SUN_STANDARD,
  sun.jnu.encoding: Cp1252,
  sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
  sun.os.patch.level: ,
  [META]class: org.apache.tamaya.functions.FilteredConfiguration,
  [META]info.filter: java.v,sun,
  [META]info.format: text/plain,
  [META]info.timestamp: 1441463082020,
  [META]timestamp: 1441463082021,
  [META]type: Configuration
-----------------------------------------------


.Formatting for +application/html+

[source, html]
-----------------------------------------------
<html>
<head><title>System Configuration</title></head>
<body>
<h1>Sysem Configuration</h1>
<p>This view shows the system configuration of devbox-win at Sat Sep 05 16:30:59 CEST 2015.</p><pre>
Configuration:
  java.vendor.url: http://java.oracle.com/,
  java.vendor.url.bug: http://bugreport.sun.com/bugreport/,
  java.vm.info: mixed mode,
  java.vm.name: Java HotSpot(TM) 64-Bit Server VM,
  java.vm.specification.name: Java Virtual Machine Specification,
  java.vm.specification.vendor: Oracle Corporation,
  java.vm.specification.version: 1.8,
  java.vm.vendor: Oracle Corporation,
  java.vm.version: 25.45-b02,
  sun.arch.data.model: 64,
  sun.boot.class.path: C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes,
  sun.boot.library.path: C:\apps\jdk18\jre\bin,
  sun.cpu.endian: little,
  sun.cpu.isalist: amd64,
  sun.desktop: windows,
  sun.io.unicode.encoding: UnicodeLittle,
  sun.java.command: com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start,
  sun.java.launcher: SUN_STANDARD,
  sun.jnu.encoding: Cp1252,
  sun.management.compiler: HotSpot 64-Bit Tiered Compilers,
  sun.os.patch.level: ,
  [META]class: org.apache.tamaya.functions.FilteredConfiguration,
  [META]info.filter: java.v,sun,
  [META]info.format: text/html,
  [META]info.timestamp: 1441463459653,
  [META]timestamp: 1441463459654,
  [META]type: Configuration
</pre>
</body>
</html>
-----------------------------------------------