add javadoc

unirest/src/main/java/kong/unirest/core/json/CoreFactory.java

@@ -31,6 +31,23 @@
 import java.util.ServiceLoader;
 import java.util.function.Supplier;
 
+/**
+ * The CoreFactory is a service locator for JsonEngines
+ * Because core does not have a dependency on the various Json implementations
+ * this class automatically finds and holds on to a implementation.
+ *
+ * It will look in the following places in this order:
+ *  1. use the java.util.ServiceLoader to load a class by looking for a meta config file in
+ *     the resources. They should exist at META-INF.services/kong.unirest.core.json.JsonEngine
+ *     The ServiceLoader will use the first one it finds.
+ *     see https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html
+ *
+ *  2. It will attempt to load the loader by class name from the classloader by known names in order. These are:
+ *      1. kong.unirest.jackson.JacksonEngine
+ *      2. kong.unirest.gson.GsonEngine
+ *
+ *  3. Clients may set a engine with the setEngine method
+ */
 public class CoreFactory {
     private static final List<Supplier<JsonEngine>> SERVICE_LOCATORS = List.of(
             CoreFactory::findEngineWithServiceLocator,
@@ -48,21 +65,46 @@ public class CoreFactory {
         autoConfig();
     }
 
+    /**
+     * Automatically find and register a JsonEngine.
+     * This method is called by the static block of this class.
+     */
     public static void autoConfig() {
         engine = findEngine();
     }
 
+    /**
+     * Gets the registered instance
+     * @return the JsonEngine registered with this class
+     * @throws UnirestConfigException if there is no known instance
+     */
     public static JsonEngine getCore() {
         if(engine == null){
             throw getException();
         }
         return engine;
     }
 
+    /**
+     * Sets the locators engine to a specific instance
+     * @param jsonEngine the engine you wish to register
+     */
     public static void setEngine(JsonEngine jsonEngine){
         engine = jsonEngine;
     }
 
+    /**
+     * Attempt to find the engine by one of the two strategies
+     *  1. use the java.util.ServiceLoader to load a class by looking for a meta config file in
+     *     the resources. They should exist at META-INF.services/kong.unirest.core.json.JsonEngine
+     *     The ServiceLoader will use the first one it finds.
+     *     see https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html
+     *
+     *  2. It will attempt to load the loader by class name from the classloader by known names in order. These are:
+     *      1. kong.unirest.jackson.JacksonEngine
+     *      2. kong.unirest.gson.GsonEngine
+     * @return the first JsonEngine it finds
+     */
     public static JsonEngine findEngine() {
         for(Supplier<JsonEngine> engineSupplier : SERVICE_LOCATORS){
             var foundEngine = engineSupplier.get();
@@ -73,12 +115,26 @@ public static JsonEngine findEngine() {
         return null;
     }
 
+    /**
+     * Finds an engine with the ServiceLoader
+     * uses the java.util.ServiceLoader to load a class by looking for a meta config file in
+     *     the resources. They should exist at META-INF.services/kong.unirest.core.json.JsonEngine
+     *     The ServiceLoader will use the first one it finds.
+     *     see https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html
+     * @return the first JsonEngine it finds
+     */
     public static JsonEngine findEngineWithServiceLocator() {
         return ServiceLoader.load(JsonEngine.class)
                 .findFirst()
                 .orElse(null);
     }
 
+    /**
+     * It will attempt to load the loader by class name from the classloader by known names in order. These are:
+     *      1. kong.unirest.jackson.JacksonEngine
+     *      2. kong.unirest.gson.GsonEngine
+     *  @return the first JsonEngine it finds
+     */
     public static JsonEngine findEngineWithClassLoader() {
         for(String className : KNOWN_IMPLEMENTATIONS) {
             try {