org.chronos.common.builder.ChronoBuilder Maven / Gradle / Ivy

Go to download
package org.chronos.common.builder;

import java.io.File;
import java.util.Map;

/**
 * A generic builder interface that allows setting properties as key-value pairs.
 *
 * @author [email protected] -- Initial Contribution and API
 *
 * @param 
 *            The dynamic type of this to return for method chaining.
 */
public interface ChronoBuilder> {

	/**
	 * Sets the given property on this builder to the given value.
	 *
	 * @param key
	 *            The key to set. Must not be null.
	 * @param value
	 *            The value to set. Must not be null.
	 * @return this (for fluent method chaining).
	 */
	public SELF withProperty(String key, String value);

	/**
	 * Loads the given properties file as configuration for this builder.
	 *
	 * 
	 * The file must fulfill all of the following conditions:
	 * 

	 * The file must be a file, not a directory.
	 * 
The file must exist.
	 * 
The file must be accessible.
	 * 
The file name must end with .properties
	 * 
The file contents must follow the default {@link java.util.Properties} format.
	 * 
	 *
	 * @param file
	 *            The properties file to read. Must not be null, must adhere to all of the conditions
	 *            stated above.
	 * @return this (for fluent method chaining).
	 */
	public SELF withPropertiesFile(File file);

	/**
	 * Loads the properties file via the given path as configuration for this builder.
	 *
	 * 
	 * The file given by the path must fulfill all of the following conditions:
	 * 

	 * The file must be a file, not a directory.
	 * 
The file must exist.
	 * 
The file must be accessible.
	 * 
The file name must end with .properties
	 * 
The file contents must follow the default {@link java.util.Properties} format.
	 * 
	 *
	 * @param filePath
	 *            The file path to the properties file to read. Must not be null, must adhere to all of the
	 *            conditions stated above.
	 * @return this (for fluent method chaining).
	 */
	public SELF withPropertiesFile(String filePath);


	/**
	 * Returns an unmodifiable map of all properties which have been collected on this builder so far.
	 *
	 * 
	 * The returned map is an immutable snapshot copy of the current state.
	 * 
	 *
	 * @return The properties collected by this builder, as an immutable map snapshot. May be empty, but never null.
	 */
	public Map getProperties();

}