.checkstyle

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<fileset-config file-format-version="1.2.0" simple-config="false" sync-formatter="true">
+  <local-check-config name="maven-checkstyle-plugin default" location="http://www.fuin.org/files/checkstyle-2018-05-01.xml" type="remote" description="maven-checkstyle-plugin configuration default">
+    <property name="checkstyle.cache.file" value="${project_loc}/target/checkstyle-cachefile"/>
+  </local-check-config>
+  <fileset name="java-sources-default" enabled="true" check-config-name="maven-checkstyle-plugin default" local="true">
+    <file-match-pattern match-pattern="^src/main/resources.*\.properties" exclude-pattern="true"/>
+    <file-match-pattern match-pattern="^src/test/resources/.*\.properties" exclude-pattern="true"/>
+  </fileset>
+</fileset-config>

.gitignore

@@ -1,6 +1,7 @@
 .*
 !.gitignore
 !.gitkeep
+!.checkstyle
 target
 META-INF
 *.log

README.md

@@ -6,6 +6,7 @@ A small Java library that contains several helpful utility classes.
 [![Build Status](https://fuin-org.ci.cloudbees.com/job/utils4j/badge/icon)](https://fuin-org.ci.cloudbees.com/job/utils4j/)
 [![Coverage Status](https://coveralls.io/repos/fuinorg/utils4j/badge.svg?branch=master)](https://coveralls.io/r/fuinorg/utils4j?branch=master)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.fuin/utils4j/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.fuin/utils4j/)
+[![Javadocs](https://www.javadoc.io/badge/org.fuin/utils4j.svg)](https://www.javadoc.io/doc/org.fuin/utils4j)
 [![LGPLv3 License](http://img.shields.io/badge/license-LGPLv3-blue.svg)](https://www.gnu.org/licenses/lgpl.html)
 [![Java Development Kit 1.8](https://img.shields.io/badge/JDK-1.8-green.svg)](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
 
@@ -15,15 +16,31 @@ A small Java library that contains several helpful utility classes.
 
 * * *
 
-##Features
+# Features
 
-###URL support for "classpath:" scheme
+* [URL support for "classpath:" scheme](#url-support-for-classpath-scheme)
+* [Variable resolver](#variable-resolver)
+* [ZIP and UNZIP](#zip-and-unzip)
+* [Tracking changes of a list / map](##tracking-changes-of-a-list--map)
+* [Easy file locking](#easy-file-locking)
+* [Properties file preferences](#properties-file-preferences)
+* [JAXB CDATA Stream Writer](#jaxb-cdata-stream-writer)
+* [Wait for code to finish](#wait-for-code-to-finish)
+* [Find all JARs and classes in the classpath](#find-all-jars-and-classes-in-the-classpath)
+* [Analyze classes in the classpath with Jandex](#analyze-classes-in-the-classpath-with-jandex)
+
+* * *
+
+# Description
+
+### URL support for "classpath:" scheme
 ```Java
 URL url = Utils4J.url("classpath:org/fuin/utils4j/test.properties");
 ```
 A full example can be found here: [ClasspathURLExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/ClasspathURLExample.java)
 
-###Variable resolver
+
+### Variable resolver
 Resolves variable references in a map and prevents on cycles.
 ```
 a=1
@@ -38,7 +55,8 @@ c=1/2/3
 ```
 A full example can be found here: [VariableResolverExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/VariableResolverExample.java)
 
-###ZIP and UNZIP
+
+### ZIP and UNZIP
 Compress and descompress a complete directory and it's subdirectories with a single line of code
 ```Java
 final File zipDir = new File(Utils4J.getTempDir(), "mydir");
@@ -48,7 +66,8 @@ Utils4J.unzip(zipFile, Utils4J.getTempDir());
 ```
 A full example can be found here: [ZipDirExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/ZipDirExample.java)
 
-###Tracking changes of a list / map
+
+### Tracking changes of a list / map
 This is a wrapper for lists that keeps track of all changes made to the list. This means adding, replacing or deleting elements is tracked - not the changes to the objects itself. It's also possible to revert (undo) all changes made to the list. A restriction is that no duplicate elements are allowed in the list.
 ```Java
 List<String> list = new ArrayList<>();
@@ -61,7 +80,9 @@ trackingList.revert();
 A list example can be found here: [ChangeTrackingUniqueListExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/ChangeTrackingUniqueListExample.java)
 A map example can be found here: [ChangeTrackingMapExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/ChangeTrackingMapExample.java)
 
-###Easy file locking
+
+### Easy file locking
+Allows to synchronize local processes by using a file based lock.
 ```Java
 FileLock lock = Utils4J.lockRandomAccessFile(randomAccessFile, tryLockMax, tryWaitMillis);
 try {
@@ -72,17 +93,162 @@ try {
 ```
 A full example can be found here: [LockFileExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/LockFileExample.java)
 
-###Properties file preferences
+
+### Properties file preferences
 Shows the use of a directory and properties file based [Preferences API](http://docs.oracle.com/javase/7/docs/technotes/guides/preferences/) implementation. It's basically a replacement for the registry based implementation on Windows.
 ```Java
 System.setProperty("java.util.prefs.PreferencesFactory",  PropertiesFilePreferencesFactory.class.getName());
 Preferences userPrefs = Preferences.userRoot();
 ```
 A full example can be found here: [PropertiesFilePreferencesFactoryExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/PropertiesFilePreferencesFactoryExample.java)
 
+
+### JAXB CDATA Stream Writer
+
+XML stream writer that does **not** escape the content of a CDATA section. 
+This is meant to be used with JAXB to serialize a string field to a CDATA section. 
+The field to write as CDATA section is annotated with a CDataXmlAdapter.
+
+Example of class using the adapter:
+```Java
+/**
+ * Example class with CDATA field.
+ */
+@XmlRootElement(name = "my-class-with-cdata")
+public final class MyClassWithCData {
+
+    // Field has the CDataXmlAdapter
+    @XmlValue
+    @XmlJavaTypeAdapter(CDataXmlAdapter.class)
+    private String content;
+
+}
+```
+If you just need to unmarshal a CDATA section, using the above annotation is all you need to do.
+
+If you need to marshal a class with CDATA content you need to use the CDataXmlStreamWriter:
+```Java
+// Create writers
+final StringWriter writer = new StringWriter();
+final XMLStreamWriter xmlWriter = XMLOutputFactory.newInstance().createXMLStreamWriter(writer);
+final CDataXmlStreamWriter cdataWriter = new CDataXmlStreamWriter(xmlWriter);
+
+// Create JAXB context with example class
+final JAXBContext ctx = JAXBContext.newInstance(MyClassWithCData.class);
+final MyClassWithCData testee = new MyClassWithCData("<whatever this=\"is\"/>");
+
+// Convert instance to XML
+marshal(ctx, testee, null, cdataWriter);
+final String xml = writer.toString();
+
+// Prints out the result
+System.out.println(xml);
+// <?xml version="1.0" ?><my-class-with-cdata><![CDATA[<whatever this="is"/>]]></my-class-with-cdata>
+
+// Convert it back to object
+final MyClassWithCData copy = unmarshal(xml, MyClassWithCData.class);
+
+// Print out cdata content
+System.out.println(copy.getContent());
+// <whatever this="is"/>
+```
+
+A full example can be found here: [CDataJaxbExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/CDataJaxbExample.java)
+
+
+### Wait for code to finish
+
+The [WaitHelper](https://github.com/fuinorg/utils4j/blob/master/src/main/java/org/fuin/utils4j/WaitHelper.java) class supports waiting for some condition.
+
+Example of waiting for a function to finish without an exception: 
+```Java
+// Try 5 times and wait 100 millis between tries (wait at max 10 seconds)
+final WaitHelper waitHelper = new WaitHelper(1000, 5);
+
+// Example of waiting for a customer to be found
+waitHelper.waitUntilNoMoreException(() -> {
+
+    // We want to wait some time to see if the CustomerNotFoundException 
+    // disappears and a customer name is finally loaded
+    loadCustomerName(customerId);
+
+}, Arrays.asList(CustomerNotFoundException.class));
+```
+
+Example of waiting for an expected customer name:
+```Java
+waitHelper.waitUntilResult(() -> {
+
+    // We want to wait some time to see if the CustomerNotFoundException
+    // disappears and a customer name is finally loaded
+    return loadCustomerName2(customerId);
+
+}, Arrays.asList("Peter Parker, Inc"));
+```
+
+A full example can be found here: [WaitHelperExample.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/WaitHelperExample.java)
+
+
+### Find all JARs and classes in the classpath
+Easily return a list of all classes or JAR files in the classpath.
+```Java
+// List CLASS files
+for (final File file : Utils4J.classpathFiles(Utils4J::classFile)) {
+    System.out.println(file);
+}
+
+// List JAR files that are not located in the JRE directory
+for (final File file : Utils4J.classpathFiles(Utils4J::nonJreJarFile)) {
+    System.out.println(file);
+}
+
+// List JAR files that are located in the JRE directory
+for (final File file : Utils4J.classpathFiles(Utils4J::jreJarFile)) {
+    System.out.println(file);
+}
+
+// List JAR files that are located in the boot path of the JRE
+for (final File file : Utils4J.pathsFiles(System.getProperty("sun.boot.class.path"), Utils4J::jreJarFile)) {
+    System.out.println(file);
+}
+```
+A full example can be found here: [FindJarsAndClassesInClasspath.java](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/examples/FindJarsAndClassesInClasspath.java)
+
+### Analyze classes in the classpath with Jandex
+Easily find matching types from all classes or JAR files in the classpath using [Jandex](https://github.com/wildfly/jandex)
+```Java
+List<File> knownFiles = new ArrayList<>();
+Indexer indexer = new Indexer();
+JandexUtils.indexClasspath((URLClassLoader) this.getClass().getClassLoader(), indexer, knownFiles);
+Index index = indexer.complete();
+Set<ClassInfo> implementors = index.getAllKnownImplementors(DotName.createSimple(List.class.getName()));
+
+// Print all classes that implement the 'List' interface
+for (ClassInfo ci : implementors) {
+    System.out.println(ci.name().toString());
+}
+
+// Print all files ("*.jar" and ".class") that were analyzed
+for (File file : knownFiles) {
+    System.out.println(file);
+}
+```
+A test that shows the usage can be found here: [JandexUtilsTest](https://github.com/fuinorg/utils4j/blob/master/src/test/java/org/fuin/utils4j/JandexUtilsTest.java)
+
+**Caution** - You must explicitly add the Jandex dependency to your POM if you want to use this feature, because it's defined as optional here.
+
+```xml
+<dependency>
+    <groupId>org.jboss</groupId>
+    <artifactId>jandex</artifactId>
+    <version>2.0.4.Final</version>
+</dependency>
+```
+
+
 * * *
 
-##Snapshots
+## Snapshots
 
 Snapshots can be found on the [OSS Sonatype Snapshots Repository](http://oss.sonatype.org/content/repositories/snapshots/org/fuin "Snapshot Repository"). 
 
@@ -101,5 +267,3 @@ Add the following to your .m2/settings.xml to enable snapshots in your Maven bui
     </snapshots>
 </repository>
 ```
-
-