001/* 002 * Copyright 2005,2009 Ivan SZKIBA 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package org.ini4j.tutorial; 017 018import org.ini4j.Options; 019 020import org.ini4j.sample.Dwarf; 021 022import org.ini4j.test.DwarfsData; 023import org.ini4j.test.Helper; 024 025import static org.junit.Assert.*; 026 027import java.io.File; 028import java.io.FileReader; 029import java.io.IOException; 030 031import java.util.Set; 032 033//<editor-fold defaultstate="collapsed" desc="apt documentation"> 034//| 035//| ---------------- 036//| Options Tutorial 037//| 038//|Options Tutorial - java.util.Properties replacement 039//| 040//| Options (org.ini4j.Options) is a java.util.Properties replacement with 041//| several useful features, like: 042//| 043//| * variable/macro substitution. You may refer to other property's value with 044//| $\{NAME\} expression, where NAME is the name of the referred property. 045//| ofcourse you can use more than one property reference per property, and 046//| you can mix constant text and property references: 047//| 048//|+-------------------+ 049//|player.name = Joe 050//|player.greetings = Hi ${player.name}! 051//|player.domain = foo.bar 052//|player.email = ${player.name}@${player.domain} 053//|+-------------------+ 054//| 055//| * multiply property values. You can refer to multi value properties with 056//| integer indexes. Ofcource it is also works in macro/variable substitutions: 057//| $\{user.fortuneNumber\[2\]\} 058//| 059//|+-------------------+ 060//|player.fortuneNumber = 33 061//|player.fortuneNumber = 44 062//|player.fortuneNumber = 55 063//|player.fortuneNumber = 66 064//| 065//|magicNumber = ${player.foruneNumber[1]} 066//|+--------------------+ 067//| 068//| The magicNumber property will have value: <<<44>>> 069//| 070//| * as Java class, Options is basicly map of Strings indexed with Strings. It 071//| is standard Collection API (ok, it is a bit enhanced to deal with multi 072//| values, but in general it is a Map\<String,String\>). 073//| 074//| * Java Beans api. You can read/write properties in type safe way. To do it 075//| you just define an interface, call Options#as() method. This method will 076//| provide an implementation of given interface on top of Options. Property 077//| types are mapped automatically between Java type and String. 078//| 079//|* Why need Options 080//| 081//| With standard Properties class there is several small problem. Most of them 082//| came from backward compatibility. 083//| 084//| * not implements Map\<String,String\>, but Map\<Object,Object\>. If you 085//| want to use Collections api, it is a bit unconfortable. 086//| 087//| * only single property values allowed. Probably you already see ugly 088//| workarounds: index number in property names, like: file.1, file.2 ... 089//| 090//| * no macro/variable substitution. In some environment, like 091//| Apache Ant, you can use ${name} like references, but with standard 092//| java.util.Properties you can't. 093//| 094//| As side effect of \[ini4j\] development, there is a solution for aboves. 095//| This is the org.ini4j.Options class, which is basicly a feature rich 096//| replacement for java.util.Properties. 097//| 098//| Code sniplets in this tutorial tested with the following .opt file: 099//| {{{../sample/dwarfs.opt.html}dwarfs.opt}} 100//| 101//</editor-fold> 102public class OptTutorial extends AbstractTutorial 103{ 104 public static final String FILENAME = "../sample/dwarfs.opt"; 105 106 public static void main(String[] args) throws Exception 107 { 108 new OptTutorial().run(filearg(args)); 109 } 110 111 protected void run(File arg) throws Exception 112 { 113 Options opt = new Options(arg.toURI().toURL()); 114 115 sample01(arg); 116 sample02(opt); 117 } 118 119//| 120//|* Instantiating 121//| 122//| There is nothing special with instantiating Options object, but there is a 123//| few constructor, to simplify loading data. These constructors simply call 124//| the <<<load()>>> method on newly created instance. Ofcource these 125//| constructors are throws IOException. 126//{ 127 void sample01(File file) throws IOException 128 { 129 Options opt = new Options(); 130 131 // 132 // or instantiate and load data: 133 // 134 opt = new Options(new FileReader(file)); 135 136//} 137 assertFalse(opt.keySet().isEmpty()); 138 } 139 140//| 141//|* Map of String 142//{ 143 void sample02(Options opt) 144 { 145 Set<String> optionNames = opt.keySet(); 146 147 // 148 String age = opt.get("age"); 149 String weight = opt.fetch("weight"); 150 String height = opt.fetch("height"); 151 152//} 153//| 154//| The Options is a MultiMap\<String,String\>, that is, a map that assigns 155//| String values to String keys. So the <<<get>>> method is used to get values 156//| inside the options. To get a value, besides <<<get()>>> you can also 157//| use <<<fetch()>>> which resolves any occurrent $\{option\} format 158//| variable references in the needed value. 159 Helper.assertEquals(DwarfsData.dopey, opt.as(Dwarf.class)); 160 } 161}