From commits-return-5097-archive-asf-public=cust-asf.ponee.io@juneau.apache.org Sat Feb 10 19:14:53 2018 Return-Path: X-Original-To: archive-asf-public@eu.ponee.io Delivered-To: archive-asf-public@eu.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by mx-eu-01.ponee.io (Postfix) with ESMTP id F092118061A for ; Sat, 10 Feb 2018 19:14:52 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id E0729160C4D; Sat, 10 Feb 2018 18:14:52 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id D70A9160C3D for ; Sat, 10 Feb 2018 19:14:51 +0100 (CET) Received: (qmail 33159 invoked by uid 500); 10 Feb 2018 18:14:51 -0000 Mailing-List: contact commits-help@juneau.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@juneau.apache.org Delivered-To: mailing list commits@juneau.apache.org Received: (qmail 33150 invoked by uid 99); 10 Feb 2018 18:14:51 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 10 Feb 2018 18:14:51 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id 7CE3D82483; Sat, 10 Feb 2018 18:14:50 +0000 (UTC) Date: Sat, 10 Feb 2018 18:14:50 +0000 To: "commits@juneau.apache.org" Subject: [juneau] branch master updated: Update Javadocs MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Message-ID: <151828649026.666.13160329924270125871@gitbox.apache.org> From: jamesbognar@apache.org X-Git-Host: gitbox.apache.org X-Git-Repo: juneau X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: 94b074d2a5aa6ba013783eca83b6469f2663d3dd X-Git-Newrev: 26efaa85b9c8f6491ad62a59b6d25e691b4f7b18 X-Git-Rev: 26efaa85b9c8f6491ad62a59b6d25e691b4f7b18 X-Git-NotificationType: ref_changed_plus_diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated This is an automated email from the ASF dual-hosted git repository. jamesbognar pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/juneau.git The following commit(s) were added to refs/heads/master by this push: new 26efaa8 Update Javadocs 26efaa8 is described below commit 26efaa85b9c8f6491ad62a59b6d25e691b4f7b18 Author: JamesBognar AuthorDate: Sat Feb 10 13:14:48 2018 -0500 Update Javadocs --- juneau-doc/src/main/javadoc/overview.html | 273 +++++++----------------------- 1 file changed, 65 insertions(+), 208 deletions(-) diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html index ea15798..88eef11 100644 --- a/juneau-doc/src/main/javadoc/overview.html +++ b/juneau-doc/src/main/javadoc/overview.html @@ -4646,13 +4646,18 @@

org.apache.juneau.config_7.0.0.jar

-

- The juneau-config library contains a powerful API for creating and using INI-style config files. -

-

- An example of an INI file: -

-

+ + + +

6.1 - Overview

+
+

+ The juneau-config library contains a powerful API for creating and using INI-style config files. +

+

+ An example of an INI file: +

+

# Default section key1 = 1 key2 = true @@ -4665,11 +4670,11 @@ key2 = false key3 = [4,5,6] key4 = http://bar -

-

- This class can be used to easily access contents of the file: -

-

+

+

+ This class can be used to easily access contents of the file: +

+

int key1; boolean key2; int[] key3; @@ -4689,11 +4694,11 @@ key2 = f.getBoolean("Section1/key2"); key3 = f.getObject(int[].class, "Section1/key3"); key4 = f.getObject(URL.class, "Section1/key4"); -

-

- The interface also allows a config file to be easily constructed programmatically: -

-

+

+

+ The interface also allows a config file to be easily constructed programmatically: +

+

// Construct the sample INI file programmatically ConfigFile cf = ConfigFile.create().build("MyConfig.cfg") .addLines(null, @@ -4711,12 +4716,12 @@ "key3 = [4,5,6]", "key4 = http://bar") .save(); -

-

- The following is equivalent, except that it uses {@link org.apache.juneau.ini.ConfigFile#put(String, Object)} - to set values: -

-

+

+

+ The following is equivalent, except that it uses {@link org.apache.juneau.ini.ConfigFile#put(String, Object)} + to set values: +

+

// Construct the sample INI file programmatically ConfigFile cf = ConfigFile.create().build("MyConfig.cfg") .addLines(null, @@ -4732,29 +4737,29 @@ cf.put("Section1/key3", new int[]{4,5,6}); cf.put("Section1/key4", new URL("http://bar")); cf.save(); -

-

- Values are LAX JSON (i.e. unquoted attributes, single quotes) except for top-level strings which are left - unquoted. - Any parsable object types are supported as values (e.g. arrays, collections, beans, swappable objects, - enums, etc...). -

-

- The config file looks deceptively simple, the config file API is a very powerful feature with many - capabilities, including: -

-
    -
  • - The ability to use variables to reference environment variables, system properties, other config file - entries, and a host of other types. -
  • - APIs for updating, modifying, and saving configuration files without losing comments or formatting. -
  • - Extensive listener APIs. -
- -
Example:
-

+

+

+ Values are LAX JSON (i.e. unquoted attributes, single quotes) except for top-level strings which are left + unquoted. + Any parsable object types are supported as values (e.g. arrays, collections, beans, swappable objects, + enums, etc...). +

+

+ The config file looks deceptively simple, the config file API is a very powerful feature with many + capabilities, including: +

+
    +
  • + The ability to use variables to reference environment variables, system properties, other config file + entries, and a host of other types. +
  • + APIs for updating, modifying, and saving configuration files without losing comments or formatting. +
  • + Extensive listener APIs. +
+ +
Example:
+

#-------------------------- # My section #-------------------------- @@ -4798,8 +4803,8 @@ # A POJO with embedded variables aBean2 = {foo:'$ARG{0}',baz:$C{MySection/anInt}} -

-

+

+

// Java code for accessing config entries above. ConfigFile cf = Microservice.getConfig(); @@ -4814,12 +4819,12 @@ int sameAsAnInt = cf.getInt("MySection/sameAsAnInt"); String myArg = cf.getString("MySection/myArg"); String firstArg = cf.getString("MySection/firstArg"); -

-

- Config files can also be used to directly populate beans using the - {@link org.apache.juneau.ini.ConfigFile#getSectionAsBean(String,Class,boolean)}: -

-

+

+

+ Config files can also be used to directly populate beans using the + {@link org.apache.juneau.ini.ConfigFile#getSectionAsBean(String,Class,boolean)}: +

+

// Example config file [MyAddress] name = John Smith @@ -4838,12 +4843,12 @@ // Example usage ConfigFile cf = ConfigFile.create().build("MyConfig.cfg"); Address myAddress = cf.getSectionAsBean("MySection", Address.class); -

-

- Config file sections can also be accessed via interface proxies using - {@link org.apache.juneau.ini.ConfigFile#getSectionAsInterface(String,Class)}: -

-

+

+

+ Config file sections can also be accessed via interface proxies using + {@link org.apache.juneau.ini.ConfigFile#getSectionAsInterface(String,Class)}: +

+

// Example config file [MySection] string = foo @@ -4881,154 +4886,6 @@ int myInt = ci.getInt(); ci.setBean(new MyBean()); cf.save(); -

- - - -

6.1 - Overview

-
-

- The {@link org.apache.juneau.ini.ConfigFileBuilder} and {@link org.apache.juneau.ini.ConfigFile} classes - implement an API for working with INI-style configuration files such as the following: -

-

- #-------------------------- - # Default section - #-------------------------- - key1 = 1 - key2 = true - key3 = 1,2,3 - key4 = http://foo - - #-------------------------- - # A comment about Section 1 - #-------------------------- - [Section1] - key1 = 2 - key2 = false - key3 = 4,5,6 - key4 = http://bar -

- -

- The {@link org.apache.juneau.ini.ConfigFileBuilder} class is used to instantiate instances of - {@link org.apache.juneau.ini.ConfigFile} which can then be used to retrieve config file values through either - "key" or "Section/key" identifiers. -

- -

- int key1; - boolean key2; - int[] key3; - URL key4; - - // Get our config file using the default config manager - ConfigFile f = ConfigFile.create().build("C:/temp/MyConfig.cfg"); - - // Read values from default section - key1 = f.getInt("key1"); - key2 = f.getBoolean("key2"); - key3 = f.getObject(int[].class, "key3"); - key4 = f.getObject(URL.class, "key4"); - - // Read values from Section #1 - key1 = f.getInt("Section1/key1"); - key2 = f.getBoolean("Section1/key2"); - key3 = f.getObject(int[].class, "Section1/key3"); - key4 = f.getObject(URL.class, "Section1/key4"); -

- -

- The interface also allows config files to be constructed programmatically... -

- -

- // Construct the sample INI file programmatically - ConfigFile f = ConfigFile.create().build("C:/temp/MyConfig.cfg", true) - .addLines(null, // The default 'null' section - "# Default section", // A regular comment - "key1 = 1", // A numeric entry - "key2 = true", // A boolean entry - "key3 = 1,2,3", // An array entry - "key4 = http://foo", // A POJO entry - "") // A blank line - .addHeaderComments("Section1", // The 'Section1' section - "A comment about Section 1") // A header comment - .addLines("Section1", // The 'Section1' section - "key1 = 2", // A numeric entry - "key2 = false", // A boolean entry - "key3 = 4,5,6", // An array entry - "key4 = http://bar") // A POJO entry - .save(); // Save to MyConfig.cfg -

- -

- The following is equivalent, except uses {@link org.apache.juneau.ini.ConfigFile#put(String,Object)} to set values. - Note how we're setting values as POJOs which will be automatically converted to strings when persisted to disk. -

- // Construct the sample INI file programmatically - ConfigFile f = ConfigFile.create().build("C:/temp/MyConfig.cfg", true) - .addLines(null, - "# Default section") - .addHeaderComments("Section1", - "A comment about Section 1"); - cf.put("key1", 1); - cf.put("key2", true); - cf.put("key3", new int[]{1,2,3}); - cf.put("key4", new URL("http://foo")); - cf.put("Section1/key1", 2); - cf.put("Section1/key2", false); - cf.put("Section1/key3", new int[]{4,5,6}); - cf.put("Section1/key4", new URL("http://bar")); - cf.save(); -

-

- Refer to {@link org.apache.juneau.ini.ConfigFile#put(String,Object,boolean)} for a description of - formats for various data types. -

-

- Various convenience getter methods are provided for retrieving different data types: -

-

- // Strings with default values - // key1 = foobar - String key1 = cf.getString("key1"); - - // Numbers - // key2 = 123 - float key2 = cf.getObject(float.class, "key2"); - - // Booleans - // key3 = true - boolean key3 = cf.getBoolean("key3"); - - // Objects convertable to and from strings using the JSON serializer and parser - // key4 = http://foo - URL key4 = cf.getObject(URL.class, "key4"); - - // Arrays of strings - // key5 = foo, bar - String[] key5 = cf.getStringArray("key5"); - - // Arrays of objects - // key6 = http://foo,http://bar - URL[] key6 = cf.getObject(URL[].class, "key6"); - - // Arrays of primitives - // key7 = 1,2,3 - int[] key7 = cf.getObject(int[].class, "key7"); - - // Enums - // key8 = MINUTES - TimeUnit key8 = cf.getObject(TimeUnit.class, "key8"); - - // Beans - // key9 = {name:'John Smith', addresses:[{street:'101 Main St', city:'Anywhere', state:'TX'}]} - Person key9 = cf.getObject(Person.class, "key9"); - - // Generic Maps - // key10 = {foo:'bar', baz:123} - Map key10 = cf.getObject(ObjectMap.class, "key10");

-- To stop receiving notification emails like this one, please contact jamesbognar@apache.org.