(maint) Update documentation on how to use configuration

Author: cardil

README.md

@@ -30,12 +30,12 @@ class Person {
 
 // inspect an object  
 List<Person> people = query.getResultList();  
-ObjectStringifier stringifier = new ObjectStringifier(people);  
-stringifier.setMode(Mode.PROMISCUOUS);
-// stringifier.setBeanFactory(...);
+Stringify stringify = Stringify.of(people);
+stringify.mode(Mode.PROMISCUOUS);
+// stringify.beanFactory(...);
 assert "<Person id=15, parent=<Person id=16, parent=null, "  
  + "childs=[(↻)], account=⁂Lazy>, childs=[], "  
- + "account=⁂Lazy>".equals(stringifier.toString());  
+ + "account=⁂Lazy>".equals(stringify.toString());  
 ```
 
  ### In Quiet mode
@@ -51,11 +51,11 @@ class Person {
 
 // inspect an object  
 List<Person> people = query.getResultList();  
-ObjectStringifier stringifier = new ObjectStringifier(people);  
-stringifier.setMode(Mode.QUIET);
+Stringify stringify = Stringify.of(people);
+stringify.mode(Mode.QUIET);
 assert "<Person id=15, parent=<Person id=16, parent=null, "  
  + "childs=[(↻)], account=⁂Lazy>, childs=[], "  
- + "account=⁂Lazy>".equals(stringifier.toString());  
+ + "account=⁂Lazy>".equals(stringify.toString());  
 ```  
 
 ## Features  
@@ -83,9 +83,100 @@ Stringify Object for Java is designed to inspect complex objects that can have c
  * Lombok can't **detect cycles** is object graph, which implies `StackOverflowException` being thrown in that case  
  * Lombok can't detect a **lazy loaded entities**, which leads to force loading it from JPA by invoking SQL statements. It's typical **n+1 problem**, but with nasty consequences - your `toString()` method is invoking SQL without your knowledge!!  
 
+## Configuration
+
+Configuration is done in two ways: declarative - using Java's service loader mechanism,
+ and programmatic.
+ 
+### Configuration using Service Loader
+
+A `Configurator` interface is intended to be implemented in user code, and assigned 
+to [Service Loader](https://www.baeldung.com/java-spi) mechanism.
+
+To do that, create on your classpath, a file:
+
+`/META-INF/services/pl.wavesoftware.utils.stringify.spi.Configurator`
+
+In that file, place a fully qualified class name of your class that implements 
+`Configurator` interface. It should be called first time you use an Stringify to inspect 
+an object:
+
+```
+# classpath:/META-INF/services/pl.wavesoftware.utils.stringify.spi.Configurator
+org.acmecorp.StringifyConfigurator
+``` 
+
+Then implement that class in your code:
+
+```java
+package org.acmecorp;
+
+import pl.wavesoftware.utils.stringify.api.Configuration;
+import pl.wavesoftware.utils.stringify.spi.Configurator;
+
+public final class StringifyConfigurator implements Configurator {
+  
+  @Override
+  public void configure(Configuration configuration) {
+    configuration.beanFactory(new SpringBeanFactory());
+  }
+}
+```
+
+with example Spring based BeanFactory:
+
+```java
+package org.acmecorp;
+
+import org.springframework.context.event.ContextRefreshedEvent;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.annotation.Configuration;
+
+import pl.wavesoftware.utils.stringify.spi.BeanFactory;
+import pl.wavesoftware.utils.stringify.spi.BootingAware;
+
+@Configuration
+class SpringBeanFactory implements BeanFactory, BootingAware {
+  private static ApplicationContext context;
+  
+  @EventListener(ContextRefreshedEvent.class)
+  void onRefresh(ContextRefreshedEvent event) {
+    SpringBeanFactory.context = event.getApplicationContext();
+  }
+  
+  @Override
+  public <T> T create(Class<T> contractClass) {
+    return SpringBeanFactory.context.getBean(contractClass);
+  }
+
+  @Override
+  public boolean isReady() {
+    return SpringBeanFactory.context != null;
+  }
+}
+```
+
+### Programmatic configuration
+
+You can also fine tune you configuration on instance level - using methods available at
+ `Stringify` interface:
+ 
+```java
+// given
+BeanFactory beanFactory = createBeanFactory();
+Person person = createPerson();
+
+// then
+Stringify stringifier = Stringify.of(person);
+stringifier
+  .beanFactory(beanFactory)
+  .mode(Mode.QUIET)
+  .stringify();
+```
+
 ## Dependencies  
 
- * Java >= 7
+ * Java >= 8
  * [EID Exceptions](https://github.com/wavesoftware/java-eid-exceptions) library 
 
 ### Contributing  

src/main/java/pl/wavesoftware/utils/stringify/api/Configuration.java

@@ -22,19 +22,25 @@
 /**
  * A interface that represents a configuration options for this library
  * <p>
- * To use that one should implement {@link Configurator} with Java's 
- * {@link java.util.ServiceLoader ServiceLoader} mechanism.
- * <p>
- * To do that, create on your classpath, a file:
- * <pre>META-INF/services/pl.wavesoftware.utils.stringify.spi.Configurator</pre>
+ * To configure this library you either use:
+ * <ul>
+ *     <li>declarative way - using Java's {@link java.util.ServiceLoader ServiceLoader}
+ *     mechanism,</li>
+ *     <li>or programmatic way.</li>
+ * </ul>
  *
  * <p>
- * In that file, place a fully qualified class name of your class that implements
- * {@link Configurator} interface. It should be called first time you
- * use an {@link pl.wavesoftware.utils.stringify.Stringify Stringify} to inspect
- * an object.
+ * On how to use declarative way consult Javadoc of {@link Configurator}.
+ * <p>
+ * To use programmatic way, just invoke configuration methods on instance of
+ * {@link pl.wavesoftware.utils.stringify.Stringify Stringify} object.
+ * <p>
+ * {@link BeanFactory} interface can be used to create instances of classes, declared
+ * in annotations used to define inspection rules.
  *
  * @see Configurator
+ * @see BeanFactory
+ * @see pl.wavesoftware.utils.stringify.Stringify Stringify
  * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszynski</a>
  * @since 2.0.0
  */

src/main/java/pl/wavesoftware/utils/stringify/spi/Configurator.java

@@ -18,19 +18,78 @@
 
 import pl.wavesoftware.utils.stringify.api.Configuration;
 
+import java.util.ServiceLoader;
+
 /**
- * An interface to implement as a Java's {@link java.util.ServiceLoader ServiceLoader}
- * mechanism.
+ * A {@code Configurator} interface is intended to be implemented in user code, and
+ * assigned to <a href="https://www.baeldung.com/java-spi">Service Loader</a> mechanism.
  * <p>
  * To do that, create on your classpath, a file:
- * <pre>META-INF/services/pl.wavesoftware.utils.stringify.spi.Configurator</pre>
  *
- * <p>
+ * <pre>
+ * /META-INF/services/pl.wavesoftware.utils.stringify.spi.Configurator
+ * </pre>
+ *
  * In that file, place a fully qualified class name of your class that implements
- * {@link Configurator} interface. It should be called first time you
- * use an {@link pl.wavesoftware.utils.stringify.Stringify Stringify} to inspect
- * an object. 
- * 
+ * {@code Configurator} interface. It should be called first time you use an Stringify
+ * to inspect an object:
+ *
+ * <pre>
+ * # classpath:/META-INF/services/pl.wavesoftware.utils.stringify.spi.Configurator
+ * org.acmecorp.StringifyConfigurator
+ * </pre>
+ *
+ * Then implement that class in your code:
+ *
+ * <pre>
+ * package org.acmecorp;
+ *
+ * import pl.wavesoftware.utils.stringify.api.Configuration;
+ * import pl.wavesoftware.utils.stringify.spi.Configurator;
+ *
+ * public final class StringifyConfigurator implements Configurator {
+ *
+ *   &#064;Override
+ *   public void configure(Configuration configuration) {
+ *     configuration.beanFactory(new SpringBeanFactory());
+ *   }
+ * }
+ * </pre>
+ *
+ * with example Spring based BeanFactory:
+ *
+ * <pre>
+ * package org.acmecorp;
+ *
+ * import org.springframework.context.event.ContextRefreshedEvent;
+ * import org.springframework.context.ApplicationContext;
+ * import org.springframework.context.annotation.Configuration;
+ *
+ * import pl.wavesoftware.utils.stringify.spi.BeanFactory;
+ * import pl.wavesoftware.utils.stringify.spi.BootingAware;
+ *
+ * &#064;Configuration
+ * class SpringBeanFactory implements BeanFactory, BootingAware {
+ *   private static ApplicationContext context;
+ *
+ *   &#064;EventListener(ContextRefreshedEvent.class)
+ *   void onRefresh(ContextRefreshedEvent event) {
+ *     SpringBeanFactory.context = event.getApplicationContext();
+ *   }
+ *
+ *   &#064;Override
+ *   public <T> T create(Class<T> contractClass) {
+ *     return SpringBeanFactory.context.getBean(contractClass);
+ *   }
+ *
+ *   &#064;Override
+ *   public boolean isReady() {
+ *     return SpringBeanFactory.context != null;
+ *   }
+ * }
+ * </pre>
+ *
+ * @see ServiceLoader
  * @see Configuration
  * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszynski</a>
  * @since 2.0.0