add javadoc

catalog-core/src/main/java/uk/gov/justice/schema/catalog/Catalog.java

@@ -8,27 +8,60 @@
 import java.util.Optional;
 
 import org.everit.json.schema.Schema;
-import org.everit.json.schema.loader.SchemaClient;
 
+/**
+ * Main entry point into the application. Gets a fully resolved Schema by the Schema's id.
+ *
+ * <p>
+ *     Usage:
+ * </p>
+ *
+ *     <pre>
+ *     {@code
+ *
+ *       final String json = "{\"some\": \"json\"}";
+ *
+ *       final String schemaId = "http://justice.gov.uk/domain/schemas/some-json-schema.json";
+ *
+ *       final Catalog catalog = new CatalogObjectFactory().catalog();
+ *       final Optional<Schema> schema = catalog.getSchema(schemaId);
+ *
+ *       if(schema.isPresent()) {
+ *           schema.get().validate(json);
+ *       }
+ *     }
+ *     </pre>
+ */
 public class Catalog {
 
     private final RawCatalog rawCatalog;
     private final SchemaClientFactory schemaClientFactory;
     private final JsonStringToSchemaConverter jsonStringToSchemaConverter;
 
-    public Catalog(final RawCatalog rawCatalog, final SchemaClientFactory schemaClientFactory, final JsonStringToSchemaConverter jsonStringToSchemaConverter) {
+    public Catalog(
+            final RawCatalog rawCatalog,
+            final SchemaClientFactory schemaClientFactory,
+            final JsonStringToSchemaConverter jsonStringToSchemaConverter) {
         this.rawCatalog = rawCatalog;
         this.schemaClientFactory = schemaClientFactory;
         this.jsonStringToSchemaConverter = jsonStringToSchemaConverter;
     }
 
+    /**
+     * Gets a a fully resolved json {@link Schema} by its schema id
+     *
+     * @param schemaId The id of the required schema
+     * @return a fully resolved {@link Schema}
+     */
     public Optional<Schema> getSchema(final String schemaId) {
 
         final Optional<String> rawJsonSchema = rawCatalog.getRawJsonSchema(schemaId);
 
         if (rawJsonSchema.isPresent()) {
-            final SchemaClient schemaClient = schemaClientFactory.create(rawCatalog);
-            final Schema schema = jsonStringToSchemaConverter.convert(rawJsonSchema.get(), schemaClient);
+            final Schema schema = jsonStringToSchemaConverter.convert(
+                    rawJsonSchema.get(),
+                    schemaClientFactory.create(rawCatalog));
+
             return of(schema);
         }
 

catalog-core/src/main/java/uk/gov/justice/schema/catalog/CatalogObjectFactory.java

@@ -10,65 +10,108 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+/**
+ * A simple cheap way of avoiding having to use a dependency injection framework in the project.
+ * Gets a instance of an object with the object's dependencies instantiated and injected.
+ */
 public class CatalogObjectFactory {
 
+    /**
+     * @return a new instance of {@link UrlConverter}
+     */
     public UrlConverter urlConverter() {
         return new UrlConverter();
     }
 
+    /**
+     * @return a new instance of {@link ObjectMapper}
+     */
     public ObjectMapper objectMapper() {
         return new ObjectMapperProducer().objectMapper();
     }
 
+    /**
+     * @return a new instance of {@link UriResolver}
+     */
     public UriResolver uriResolver() {
         return new UriResolver();
     }
 
+    /**
+     * @return a new instance of {@link JsonStringToSchemaConverter}
+     */
     public JsonStringToSchemaConverter jsonStringToSchemaConverter() {
         return new JsonStringToSchemaConverter();
     }
 
+    /**
+     * @return a new instance of {@link ClasspathResourceLoader}
+     */
     public ClasspathResourceLoader classpathResourceLoader() {
         return new ClasspathResourceLoader();
     }
 
+    /**
+     * @return a new instance of {@link ClasspathCatalogLoader}
+     */
     public ClasspathCatalogLoader classpathCatalogLoader() {
         return new ClasspathCatalogLoader(
                 objectMapper(),
                 classpathResourceLoader(),
                 urlConverter());
     }
 
+    /**
+     * @return a new instance of {@link SchemaResolver}
+     */
     public SchemaResolver schemaResolver() {
         return new SchemaResolver(urlConverter(), uriResolver());
     }
 
+    /**
+     * @return a new instance of {@link CatalogToSchemaResolver}
+     */
     public CatalogToSchemaResolver catalogToSchemaResolver() {
         return new CatalogToSchemaResolver(
                 classpathCatalogLoader(),
                 schemaResolver(),
                 getLogger(CatalogToSchemaResolver.class));
     }
 
+    /**
+     * @return a new instance of {@link FileContentsAsStringLoader}
+     */
     public FileContentsAsStringLoader fileContentsAsStringLoader() {
         return new FileContentsAsStringLoader();
     }
 
+    /**
+     * @return a new instance of {@link JsonSchemaFileLoader}
+     */
     public JsonSchemaFileLoader jsonSchemaFileLoader() {
         return new JsonSchemaFileLoader(fileContentsAsStringLoader(), catalogToSchemaResolver());
     }
 
+    /**
+     * @return a new instance of {@link SchemaClientFactory}
+     */
     public SchemaClientFactory schemaClientFactory() {
         return new SchemaClientFactory();
     }
 
+    /**
+     * @return a new instance of {@link Catalog}
+     */
     public Catalog catalog() {
         return new Catalog(
                 rawCatalog(),
                 schemaClientFactory(),
                 jsonStringToSchemaConverter());
     }
 
+    /**
+     * @return a new instance of {@link RawCatalog}
+     */
     public RawCatalog rawCatalog() {
         final RawCatalog rawCatalog = new RawCatalog(jsonSchemaFileLoader());
         rawCatalog.initialize();

catalog-core/src/main/java/uk/gov/justice/schema/catalog/CatalogProducer.java

@@ -3,9 +3,15 @@
 import javax.enterprise.context.ApplicationScoped;
 import javax.enterprise.inject.Produces;
 
+/**
+ * A Producer for the {@link Catalog} should you be running in a CDI container
+ */
 @ApplicationScoped
 public class CatalogProducer {
 
+    /**
+     * @return a new instance of {@link Catalog}
+     */
     @Produces
     public Catalog catalog() {
         return new CatalogObjectFactory().catalog();

catalog-core/src/main/java/uk/gov/justice/schema/catalog/CatalogToSchemaResolver.java

@@ -15,6 +15,10 @@
 
 import org.slf4j.Logger;
 
+/**
+ * Finds all catalog files on the classpath, then returns a mapping of the schema id to its
+ * location.
+ */
 public class CatalogToSchemaResolver {
 
     private final ClasspathCatalogLoader classpathCatalogLoader;
@@ -30,6 +34,9 @@ public CatalogToSchemaResolver(final ClasspathCatalogLoader classpathCatalogLoad
     }
 
     /**
+     * Find all catalog files on the classpath and return a mapping of the schema id to
+     * the location of the schema file
+     *
      * @return Mapping from schemaId to a schema location url
      */
     public Map<String, URL> resolveSchemaLocations() {

catalog-core/src/main/java/uk/gov/justice/schema/catalog/ClasspathCatalogLoader.java

@@ -15,6 +15,10 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
+/**
+ * Loads all {@link Catalog}s from any part of the classpath, which have the path
+ * '/json/schema/schema_catalog.json'
+ */
 public class ClasspathCatalogLoader {
 
     private static final String DEFAULT_JSON_CATALOG_LOCATION = "json/schema/schema_catalog.json";
@@ -31,6 +35,12 @@ public ClasspathCatalogLoader(final ObjectMapper objectMapper,
         this.urlConverter = urlConverter;
     }
 
+    /**
+     * Loads all {@link Catalog}s from any part of the classpath found on the path
+     * 'json/schema/schema_catalog.json'
+     *
+     * @return All found {@link Catalog}s mapped by their URIs
+     */
     public Map<URI, Catalog> getCatalogs() {
         return listAllCatalogsFromClasspath().stream()
                 .collect(toMap(urlConverter::toUri, this::loadCatalog));

catalog-core/src/main/java/uk/gov/justice/schema/catalog/FileContentsAsStringLoader.java

@@ -8,8 +8,18 @@
 
 import org.apache.commons.io.IOUtils;
 
+/**
+ *  Gets the contents of a file as a {@link String}
+ */
 public class FileContentsAsStringLoader {
 
+    /**
+     * Gets the contents of a file as a {@link String}
+     *
+     * @param urlOfFile The {@link java.net.URI} of the file
+     *
+     * @return The File's contents as a UTF 8 String.
+     */
     public String readFileContents(final URL urlOfFile) {
 
         try  {

catalog-core/src/main/java/uk/gov/justice/schema/catalog/JsonSchemaFileLoader.java

@@ -4,16 +4,30 @@
 
 import java.util.Map;
 
+/**
+ * Loads all Json Schema files found on the classpath as a raw {@link String} mapped by the id
+ * of that Schema
+ */
 public class JsonSchemaFileLoader {
 
     private final FileContentsAsStringLoader fileContentsAsStringLoader;
     private final CatalogToSchemaResolver catalogToSchemaResolver;
 
-    public JsonSchemaFileLoader(final FileContentsAsStringLoader fileContentsAsStringLoader, final CatalogToSchemaResolver catalogToSchemaResolver) {
+    public JsonSchemaFileLoader(
+            final FileContentsAsStringLoader fileContentsAsStringLoader,
+            final CatalogToSchemaResolver catalogToSchemaResolver) {
+
         this.fileContentsAsStringLoader = fileContentsAsStringLoader;
         this.catalogToSchemaResolver = catalogToSchemaResolver;
     }
 
+    /**
+     * Loads all Json Schema files found on the classpath as a raw {@link String} mapped by the id
+     * of that Schema.
+     *
+     * @return A {@link Map} of Schemas as a raw {@link String} mapped to the
+     *         id of each Schema
+     */
     public Map<String, String> loadSchemas() {
 
         return catalogToSchemaResolver.resolveSchemaLocations().entrySet()

catalog-core/src/main/java/uk/gov/justice/schema/catalog/JsonStringToSchemaConverter.java

@@ -9,9 +9,25 @@
 import org.json.JSONObject;
 import org.json.JSONTokener;
 
+/**
+ * Converts a raw Json Schema into an Everit {@link Schema} resolving any referred Schemas
+ * in the raw Json Schema to their location on the classpath
+ */
 public class JsonStringToSchemaConverter {
 
+    /**
+     * Converts a raw Json Schema into an Everit {@link Schema} resolving any referred Schemas
+     * in the raw Json Schema to their location on the classpath
+     *
+     * @param schemaJson The raw Json Schema as a {@link String}
+     * @param schemaClient An implementation of Everit's {@link SchemaClient} that
+     *                                    rather than returning a schema found at the Schema id,
+     *                                    returns a Schema found on the classpath mapped to that
+     *                                    Schema id
+     * @return A fully resolved Everit {@link Schema}
+     */
     public Schema convert(final String schemaJson, final SchemaClient schemaClient) {
+
         try {
             return SchemaLoader.builder()
                     .schemaJson(new JSONObject(new JSONTokener(schemaJson)))

catalog-core/src/main/java/uk/gov/justice/schema/catalog/RawCatalog.java

@@ -6,6 +6,10 @@
 import java.util.Map;
 import java.util.Optional;
 
+/**
+ * Main cache of all Json Schemas found on the classpath mapped by their Schema id.
+ * All Schemas are the raw unresolved contents of the Json Schema file as a {@link String}
+ */
 public class RawCatalog {
 
     private final JsonSchemaFileLoader jsonSchemaFileLoader;
@@ -16,10 +20,20 @@ public RawCatalog(final JsonSchemaFileLoader jsonSchemaFileLoader) {
         this.jsonSchemaFileLoader = jsonSchemaFileLoader;
     }
 
+    /**
+     * Initializes the cache of raw json schemas by scanning the classpath and
+     * loading all json schemas it finds.
+     */
     public void initialize() {
         schemaIdsToRawJsonSchemaCache = jsonSchemaFileLoader.loadSchemas();
     }
 
+    /**
+     * Gets the raw unresolved json of a Schema file found on the classpath by its id.
+     * @param schemaId The id of the required json schema file
+     * @return An {@link Optional} containing the raw json schema of the schema file with
+     * the specified id, if it exists.
+     */
     public Optional<String> getRawJsonSchema(final String schemaId) {
         return ofNullable(schemaIdsToRawJsonSchemaCache.get(schemaId));
     }