/*******************************************************************************
* Copyright (c) 2012 Pivotal Software, Inc.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Pivotal Software, Inc. - initial API and implementation
*******************************************************************************/
package org.springsource.ide.eclipse.commons.frameworks.core.internal.commands;
/**
* This describes a parameter descriptor, and is intended to be IMMUTABLE.
* <p>
* To instantiate a parameter whose values can be set, see
* {@link ICommandParameter}</p>
* Example of how to define a parameter descriptor:
* <p>
* -Dsys.env=prod
* </p>
* <p>
* Here, "-D" is the prefix, "sys.env" the parameter name, "=" the value
* separator, and "prod" a default value
* </p>
* @author Nieraj Singh
*/
public interface ICommandParameterDescriptor {
/**
* This is the name of the parameter as it would appear in the actual
* command line String. It must be exactly as it would be used if a user
* would type it when executing a command in a command line.
*
* @return name of the parameter. It's required
*/
public String getName();
/**
*
* @return optional description of the parameter that may include
* information on what it does, and what values may be acceptable
*/
public String getDescription();
/**
*
* @return true if it requires a set value, false if it is an optional
* parameter
*/
public boolean isMandatory();
/**
* Identifier indicating the type of parameter. Must not be null.
*
* @return non-null indentifier.
*/
public ParameterKind getParameterKind();
/**
* Optionally, a parameter can specify a default value. Some parameters may
* always have a default value, like a boolean parameter, in which case the
* default is false. The value of the default is not expected to change
* throughout the life of the parameter, unlike the actual value.
*
* @return a default value, or null if it has no default value. Empty
* strings are considered default values, so only use null to
* indicate no default value
*/
public Object getDefaultValue();
/**
* If the parameter name needs to be included in the executable command
* string and must be prefixed by a delimiter like "--", return a non-null
* value. Return null if parameter name should not be prefixed, regardless
* of whether the parameter name itself should appear or not.
*
* @return non-null String if it has a delimiter, null if not.
*/
public String getParameterPrefix();
/**
* @return true if the parameter name forms part of the executable String,
* or false if it should be omitted.
*/
public boolean requiresParameterNameInCommand();
/**
* Optional. If a parameter requires a value separator that separates the
* value from the parameter name, like for instance '=' or ':', the
* parameter descriptor must return a non-null, non-empty separator. A null
* or empty separator will be ignored.
* <p>
* -Dsys.env=prod
* </p>
* <p>
* Here, "-D" is the prefix, "sys.env" the parameter name, and "=" the value
* separator
* </p>
*
* @return the value separator
*/
public String getValueSeparator();
}