com.reprezen.genflow.api.trace.GenTemplateTrace 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.
 *******************************************************************************/
package com.reprezen.genflow.api.trace;

import java.io.File;
import java.util.ArrayList;
import java.util.List;

import com.fasterxml.jackson.annotation.JsonIdentityInfo;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.ObjectIdGenerators;
import com.reprezen.genflow.api.template.GenTemplate;

/**
 * This class represents trace information created from the execution of a
 * GenTarget in producing a given output file.
 * 
 * The purpose of trace information is to link inputs to outputs in a way that
 * will be meaningful to consumers of the output. The most common use of trace
 * information is seen when GenTemplates are chained together. A downstream
 * GenTemplate in such an arrangement is generally viewed as operating on some
 * source model, but it makes use of the output generated by an upstream
 * GenTemplate operating on that same model. In utilizing the output of the
 * upstream GenTemplate, it is often critical to understand exactly how
 * structures in the input model relate to structures in the output generated by
 * the upstream GenTemplate, and trace information is designed to make that
 * possible.
 * 

 * The overall structure of a trace object is a collection of trace items, each
 * of which links one or more source items to a single output item. The trace
 * item itself describes the single output item, and it contains a number of
 * source item descriptors that describe the source item.
 * 

 * A source or output item refers to either a single source/output file as a
 * whole, or some portion of a source/output file, identified in a
 * file-format-specific manner. A source role descriptor also includes a string
 * that can be used to describe the role played by that specific source item in
 * the formation of the output item.
 * 
 * @author Konstantin Zaitsev
 * @date Jun 8, 2015
 */
@JsonIdentityInfo(generator = ObjectIdGenerators.IntSequenceGenerator.class)
public final class GenTemplateTrace {

	/**
	 * Generic item type created for every output file produced by GenTemplates
	 * based on {@link GenTemplate}.
	 */

	public static final String FILE_ITEM_TYPE = "file";

	/**
	 * Generic source role indicating that source data contributed to an output item
	 * in an otherwise unspecified manner.
	 */
	public static final String SOURCE_DATA_ROLE = "sourceData";

	/** Special sourceName to be used for the GenTemplate's primary source. */
	public static final String PRIMARY_SOURCE_NAME = "_primary";

	/**
	 * Special sourceName in source items generated from resources packaged with the
	 * GenTemplate.
	 */
	public static final String RESOURCE_SOURCE_NAME = "_resource";

	// protected fields for better JavaDoc generation

	/** ID of the GenTemplate that was executed by the GenTarget */
	protected String genTemplateId;

	/** Trace items created by the GenTemplate. */
	protected List traceItems = new ArrayList<>();

	/**
	 * Optional base directory used in relativizing output files during
	 * serialization.
	 * 
	 * If this value is set, it is used to relativize the output file path in each
	 * trace item while serializing the trace object to a trace file. When
	 * deserializing a trace file, a base directory can optionally be specified,
	 * which will cause the relative paths for all the trace item output files to be
	 * resolved relative to that directory in the process.
	 */
	@JsonIgnore
	protected File baseDirectory;

	/** @see #genTemplateId */
	public String getGenTemplateId() {
		return genTemplateId;
	}

	/** @see #genTemplateId */
	public void setGenTemplateId(String templateId) {
		this.genTemplateId = templateId;
	}

	/** @see #traceItems */
	public List getTraceItems() {
		return traceItems;
	}

	/** @see #traceItems */
	public void setTraceItems(List traceItems) {
		this.traceItems = traceItems;
	}

	/** @see baseDirectory */
	public File getBaseDirectory() {
		return baseDirectory;
	}

	/** @see baseDirectory */
	public void setBaseDirectory(File baseDirectory) {
		if (baseDirectory.exists() && !baseDirectory.isDirectory()) {
			baseDirectory = baseDirectory.getParentFile();
		}
		this.baseDirectory = baseDirectory;
	}

	@Override
	public String toString() {
		return "GenTemplateTrace [genTemplateId=" + genTemplateId + ", baseDirectory=" + baseDirectory + ", traceItems="
				+ traceItems + "]";
	}
}