com.reprezen.genflow.api.template.package-info Maven / Gradle / Ivy

/*******************************************************************************
 * Copyright © 2013, 2016 Modelsolv, Inc.
 * All Rights Reserved.
 *
 * NOTICE: All information contained herein is, and remains the property
 * of ModelSolv, Inc. See the file license.html in the root directory of
 * this project for further information.
 *******************************************************************************/
/**
 * This package defines interfaces and classes for GenTemplates - the heart of
 * the CodeGen framework.
 * 
 * A GenTemplate is invoked by a GenTarget, which provides bindings for items
 * required by but not specified by the GenTemplate itself - items such as
 * source files, an output directory, string parameters, etc. Prerequisite
 * GenTargets are another of these bound items supplied by the controlling
 * GenTarget. In some cases, the GenTemplate can specify constraints on the
 * bound items. For example, for a prerequisite, the GenTemplate identifies the
 * GenTemplate that must be executed by the prerequisite GenTarget. Any attempt
 * to execute this GenTemplate with a GenTarget that does not supply a
 * prerequisite GenTarget satisfying this constraint - or in general any attempt
 * to execute a GenTarget that does not satisfactorily meet all the binding
 * requirements of its GenTemplate - will fail with a
 * {@link com.reprezen.genflow.api.GenerationException}.
 * 

 * While the above considerations apply to most actual GenTemplates, the binding
 * mechanism is not visible at the most basic levels - the {@link IGenTemplate}
 * interface and the {@link AbstractGenTemplate} class. While it is still true
 * that GenTemplates built to these lower-level types must be executed by
 * GenTargets, the binding machinery is not available until one advances to
 * {@code SimpleGenTemplates}, which exposes bindings for primary source and
 * prerequisites. Further binding capabilities arise with {@link GenTemplate}.
 * 

 * Binding requirements are created in a GenTemplate implementation by
 * overriding {@link GenTemplate#configure} and including in-line definitions
 * that invoke builders, as explained in the com.reprezen.genflow.api.template.builders
 * package summary. It is also possible to place this information in a separate
 * configuration file. If {@link SimpleGentemplate#configure} is not overridden,
 * then its default implementation will defer to
 * {@link GenTemplate#configureByConfigFile()}. See its documentation and that
 * of {@link GenTemplate#configureByConfigFile()} for details.
 * 

 * A GenTemplate's binding requirements are exposed through its
 * {@link IGenTemplate#getDependencies()} method. This information is used to
 * ensure that when a collection of GenTargets are selected for execution, all
 * necessary prerequisite GenTargets are also scheduled for execution, and the
 * GenTargets are executed in the correct order.
 * 

 * A GenTemplate must include a resource named
 * META-INF/services/com.reprezen.genflow.api.template.IGenTemplate
 * in order to be available for use. The file should include the fully-qualified
 * type name of the implementing class.
 * 

 * Classes in this package include:
 * 

 * {@link IGenTemplate}
 * Describes the low-level interface by which GenTemplates are executed and
 * wired for execution.
 * {@link IGenTemplateGruop}
 * Provides a simple means of advertising multiple GenTemplates in one go.
 * Rather than creating a META-INF/services/.../IGenTemplate
 * resource for each GenTemplate individually, a resource named
 * META-INF/services/.../IGenTemplateGroup can be created, with the
 * fully qualified name of a class implementing {@link IGenTemplateGroup} as its
 * content. That implementing class can then provide multiple GenTemplate
 * exemplars for discovery.
 * {@link AbstractGenTemplate}
 * Fills in default implementations for most {@link IGenTemplate}
 * methods.
 * {@link GenTemplate}
 * This is the recommended base class for all GenTemplate development.
 * Introduces the notions of a primary source and is a generic type
 * with a type parameter specifying the type of that source. Also provides for
 * the configuration of prerequisite GenTargets and exposes them via
 * {@link IGenTemplate#getDependencies()}. Introduces the notion of multiple
 * output items, each generating content that to be saved in its own
 * output file. Each configured output item is an implementation of
 * {@link IOutputItem}.
 * 
 * This class also supports extracting embedded values from the primary source,
 * and sending each to an appropriately typed output item. This means that a
 * single output item can actually produce multiple output files from a single
 * primary source.
 * 

 * Finally, {@link GenTemplate} supports configuration of multiple named sources
 * in addition to the primary source, named parameters, and static resources.
 * The latter allows Java resources accompanying the GenTemplate implementation
 * to be copied out as part of the generated output. The prototypical example of
 * this is to provide web assets needed by a generated HTML file.
 * {@link GenTemplateDependency}
 * This class summarizes a binding requirement by a GenTemplate, supplying a
 * name, a type, a string of type-dependent additional info, and a flag
 * indicating whether the binding is actually required or merely optional.
 * Examples of additional info strings are a GenTemplate Id to constrain the
 * GenTargets that can be bound to a prerequisite, and a source value type (as a
 * class name) for a source binding.
 * {@link GenTemplateDependencies}
 * A container for dependencies. This class also provides static methods for
 * constructing dependencies, including a method for each type of configuration
 * builder spec that can give rise to a dependency.
 * {@link GenTemplateRegistry}
 * This class uses Java's {@link java.util.ServiceLoader} facility to
 * discover available GenTemplate implementations, using the
 * META-INF/services/... resources mentioned earlier.
 * 
 * 
 * @author Andy Lowry
 */
package com.reprezen.genflow.api.template;