domain/pools/Expression.java

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 *
 * ident	"%Z%%M%	%I%	%E% SMI"
 */

package com.sun.solaris.domain.pools;

import java.util.regex.*;

/**
 * This class provides the base implementation of an Expression. All
 * types of Expression must inherit from this class.
 *
 * An objective is always specified in terms of an expression. The
 * only recognized expressions are those known by this class. An
 * expression is create using the valueOf() factory method, which is
 * why Expressions must be known to this class.
 */
abstract class Expression
{
	/**
	 * Expression importance
	 */
	private long imp = -1;

	/**
	 * Expression name
	 */
	private String name;

	/**
	 * Sole constructor.  (For invocation by subclass constructors)
	 */
	protected Expression(long imp, String name)
	{
		this.imp = imp;
		this.name = name;
	}

	/**
	 * Return the name of the expression.
	 */
	String getName()
	{
		return (this.name);
	}

	/**
	 * Return the importance of the expression.
	 */
	long getImportance()
	{
		return (imp);
	}

	/**
	 * Returns the supplied string as an expression.
	 *
	 * This utility function attempts to identify the supplied
	 * string as an expression. It tries in turn each of the known
	 * sub-classes until finally, if none can be recognized, an
	 * exception is thrown. This function is not immune to
	 * mistakenly mis-classifying an expression. It is the
	 * responsibility of the concrete Exrpession classes to ensure
	 * that syntactic integrity is maintained with respect to
	 * potential cases of mistaken identity.
	 *
	 * @param raw The candidate expression
	 * @throws IllegalArgumentException If no valid expression can
	 * be found
	 */
	static Expression valueOf(String raw) throws IllegalArgumentException
	{
		Expression exp = null;
		/*
		 * TODO It would be better if subclasses registered,
		 * but this hard coded list will do until such a time
		 */
		if ((exp = KVOpExpression.valueOf(raw)) == null)
			if ((exp = KVExpression.valueOf(raw)) == null)
				exp = KExpression.valueOf(raw);
		if (exp == null)
			throw new IllegalArgumentException(
			    "unrecognized expression: " + raw);
		return (exp);
	}

	/**
	 * Ensure that the supplied importance is a valid value.
	 *
	 * @param imps String representation of the importance.
	 *
	 * @throws IllegalArgumentException if the importance is not
	 * valid.
	 */
	protected static long validateImportance(String imps)
	    throws IllegalArgumentException
	{
		long imp;

		try {
			imp = Long.parseLong(imps);
		} catch (NumberFormatException nfe) {
			throw new IllegalArgumentException("importance value " +
			    imps + " is not legal");
		}

		if (imp < 0)
			throw new IllegalArgumentException("importance value " +
			    imps + " is not legal (must be positive)");
		return (imp);
	}

	/**
	 * Ensure that the supplied keyword is a member of the
	 * supplied keys.
	 *
	 * @param keys Array of valid key strings.
	 * @param key Key sought.
	 *
	 * @throws IllegalArgumentException if the sought key is not
	 * a member of the keys array.
	 */
	protected static void validateKeyword(String keys[], String key)
	    throws IllegalArgumentException
	{
		for (int i = 0; i < keys.length; i++) {
			if (keys[i].compareTo(key) == 0)
				return;
		}
		throw new IllegalArgumentException("keyword " + key +
		    " is not recognized");
	}

	/**
	 * Return true if the supplied expression "contradicts" this
	 * expression. The definition of contradiction is left down to
	 * each implementing sub-class.
	 *
	 * @param o Expression to examine for contradiction.
	 */
	public abstract boolean contradicts(Expression o);
}

/**
 * This class implements the functionality for a key-value-operator
 * expression.
 *
 * The general form of this expression is defined in the pattern
 * member. A simplified rendition of which is:
 *
 * [[imp]:] <key> <op> <value>
 *
 * key is a string which identifies the expression
 * op is the operator for the expression ( < | > | ~)
 * value is the value of the expression
 *
 * For example:
 *
 * 10: utilization < 80
 */
final class KVOpExpression extends Expression
{
	/**
	 * The operator for this expression.
	 */
	private char op;

	/**
	 * The value of this expression.
	 */
	private int val;

	/**
	 * The pattern used to recognize this type of expression.
	 */
	private static final Pattern pattern = Pattern.compile(
	    "\\s*((\\d+)\\s*:)?\\s*(\\w+)\\s*([~<>])\\s*(\\d+)\\s*");

	/**
	 * The array of valid keys for this type of expression.
	 */
	private static final String keys[] = { "utilization" };

	/**
	 * A greater than operator.
	 */
	static final char GT = '>';

	/**
	 * A less than operator.
	 */
	static final char LT = '<';

	/**
	 * A near to operator.
	 */
	static final char NT = '~';

	/**
	 * Private constructor used in the valueOf() factory method.
	 *
	 * @param imp The importance of this expression.
	 * @param name The name of this expression.
	 * @param op The operator of this expression.
	 * @param val The value of this expression.
	 */
	private KVOpExpression(long imp, String name, String op, int val)
	{
		super(imp, name);
		this.op = op.charAt(0);
		this.val = val;
	}

	/**
	 * Create and return an expression from the input string.
	 *
	 * Determine if the input string matches the syntax defined by
	 * this expression. If the expression cannot be matched, an
	 * exception will be thrown.
	 *
	 * @param raw Candidate expression string.
	 *
	 * @throws IllegalArgumentExpression if the string is not a
	 * valid expression of this type.
	 */
	static Expression valueOf(String raw) throws IllegalArgumentException
	{
		KVOpExpression exp = null;
		Matcher m = pattern.matcher(raw);

		if (m.matches()) {
			long imp = 1;
			int val = Integer.parseInt(m.group(5));

			if (m.group(2) != null)
				imp = validateImportance(m.group(2));

			validateKeyword(keys, m.group(3));
			if (val > 100 || val < 0)
				throw new IllegalArgumentException(
				    "expression value " + val +
				    " is outside the legal range (0-100)");
			exp = new KVOpExpression(imp, m.group(3),
			    m.group(4), val);
		}
		return (exp);
	}

	/**
	 * Return the operator for this expression.
	 */
	char getOp()
	{
		return (op);
	}

	/**
	 * Return the value of this expression.
	 */
	int getValue()
	{
		return (val);
	}

	/**
	 * Return a string representation of this expresssion.
	 */
	public String toString()
	{
		return ("(" + getImportance() + ", " + getName() + ", '" + op +
		    "', " + val + ")");
	}

	/**
	 * Indicates whether some other KVOpExpression is "equal to
	 * this one.
	 * @param o the reference object with which to compare.
	 * @return <code>true</code> if this object is the same as the
	 * o argument; <code>false</code> otherwise.
	 * @see	#hashCode()
	 */
	public boolean equals(Object o)
	{
		if (o == this)
			return (true);
		if (!(o instanceof KVOpExpression))
			return (false);
		KVOpExpression other = (KVOpExpression) o;
		if (getName().compareTo(other.getName()) != 0 ||
		    op != other.getOp() || val != other.getValue())
			return (false);
		return (true);
	}

	/**
	 * Returns a hash code value for the object. This method is
	 * supported for the benefit of hashtables such as those provided by
	 * <code>java.util.Hashtable</code>.
	 *
	 * @return a hash code value for this object.
	 * @see	#equals(java.lang.Object)
	 * @see	java.util.Hashtable
	 */
	public int hashCode()
	{
		return (getName().hashCode() + (int) op + val);
	}

	/**
	 * Return true if the supplied expression "contradicts" this
	 * expression. If the supplied expression is not of the same
	 * type, then it cannot contradict it. If the names are
	 * different then there can be no contradiction.
	 *
	 * Contradiction occurs if the operator is the same or if they
	 * aren't the same and the operator is < or > and the values
	 * aren't simultanteously achievable.
	 *
	 * @param o Expression to examine for contradiction.
	 */
	public boolean contradicts(Expression o)
	{
		if (!(o instanceof KVOpExpression))
			return (false);
		KVOpExpression other = (KVOpExpression) o;
		if (getName().compareTo(other.getName()) != 0)
			return (false);
		if (getOp() != other.getOp()) {
			if (getOp() != NT && other.getOp() != NT) {
				if (getOp() == GT) {
					if (getValue() < other.getValue())
						return (false);
				} else {
					if (getValue() > other.getValue())
						return (false);
				}
			} else
				return (false);
		}
		return (true);
	}
}

/**
 * This class implements the functionality for a key-value expression.
 *
 * The general form of this expression is defined in the pattern
 * member. A simplified rendition of which is:
 *
 * [[imp]:] <key> <value>
 *
 * key is a string which identifies the expression
 * value is the value of the expression
 *
 * For example:
 *
 * 10: locality tight
 */
final class KVExpression extends Expression
{
	/**
	 * The value of this expression.
	 */
	private String val;

	/**
	 * The pattern used to recognize this type of expression.
	 */
	private static final Pattern pattern = Pattern.compile(
	    "\\s*((\\d+)\\s*:)?\\s*(\\w+)\\s+(tight|loose|none)\\s*");

	/**
	 * The array of valid keys for this type of expression.
	 */
	private static final String keys[] = { "locality" };

	/**
	 * Private constructor used in the valueOf() factory method.
	 *
	 * @param imp The importance of this expression.
	 * @param name The name of this expression.
	 * @param val The value of this expression.
	 */
	private KVExpression(long imp, String name, String val)
	{
		super(imp, name);
		this.val = val;
	}

	/**
	 * Create and return an expression from the input string.
	 *
	 * Determine if the input string matches the syntax defined by
	 * this expression. If the expression cannot be matched, an
	 * exception will be thrown.
	 *
	 * @param raw Candidate expression string.
	 *
	 * @throws IllegalArgumentExpression if the string is not a
	 * valid expression of this type.
	 */
	static Expression valueOf(String raw) throws IllegalArgumentException
	{
		KVExpression exp = null;
		Matcher m = pattern.matcher(raw);

		if (m.matches()) {
			long imp = 1;

			if (m.group(2) != null)
				imp = validateImportance(m.group(2));

			validateKeyword(keys, m.group(3));
			exp = new KVExpression(imp, m.group(3), m.group(4));
		}
		return (exp);
	}

	/**
	 * Return the value of this expression.
	 */
	String getValue()
	{
		return (val);
	}

	/**
	 * Return a string representation of this expresssion.
	 */
	public String toString()
	{
		StringBuffer buf = new StringBuffer();

		buf.append("(");
		buf.append(getImportance());
		buf.append(", ");
		buf.append(getName());
		buf.append(", ");
		buf.append(val);
		buf.append(")");

		return (buf.toString());
	}

	/**
	 * Indicates whether some other KVExpression is "equal to
	 * this one.
	 * @param o the reference object with which to compare.
	 * @return <code>true</code> if this object is the same as the
	 * o argument; <code>false</code> otherwise.
	 * @see	#hashCode()
	 */
	public boolean equals(Object o)
	{
		if (o == this)
			return (true);
		if (!(o instanceof KVExpression))
			return (false);
		KVExpression other = (KVExpression) o;
		if (getName().compareTo(other.getName()) != 0 ||
		    val.compareTo(other.getValue()) != 0)
			return (false);
		return (true);
	}

	/**
	 * Returns a hash code value for the object. This method is
	 * supported for the benefit of hashtables such as those provided by
	 * <code>java.util.Hashtable</code>.
	 *
	 * @return a hash code value for this object.
	 * @see	#equals(java.lang.Object)
	 * @see	java.util.Hashtable
	 */
	public int hashCode()
	{
		return (getName().hashCode() + val.hashCode());
	}

	/**
	 * Return true if the supplied expression "contradicts" this
	 * expression. If the supplied expression is not of the same
	 * type, then it cannot contradict it. If the names are
	 * different then there can be no contradiction.
	 *
	 * Contradiction occurs if the value is different.
	 *
	 * @param o Expression to examine for contradiction.
	 */
	public boolean contradicts(Expression o)
	{
		if (!(o instanceof KVExpression))
			return (false);
		KVExpression other = (KVExpression) o;
		if (getName().compareTo(other.getName()) != 0)
			return (false);
		if (val.compareTo(other.getValue()) == 0)
			return (false);
		return (true);
	}
}

/**
 * This class implements the functionality for a key expression.
 *
 * The general form of this expression is defined in the pattern
 * member. A simplified rendition of which is:
 *
 * [[imp]:] <key>
 *
 * key is a string which identifies the expression
 *
 * For example:
 *
 * 10: wt-load
 */
final class KExpression extends Expression
{
	/**
	 * The pattern used to recognize this type of expression.
	 */
	private static final Pattern pattern = Pattern.compile(
	    "\\s*((\\d+)\\s*:)?\\s*([\\w-]+)\\s*");

	/**
	 * The array of valid keys for this type of expression.
	 */
	private static final String keys[] = { "wt-load" };

	/**
	 * Private constructor used in the valueOf() factory method.
	 *
	 * @param imp The importance of this expression.
	 * @param name The name of this expression.
	 */
	private KExpression(long imp, String name)
	{
		super(imp, name);
	}

	/**
	 * Create and return an expression from the input string.
	 *
	 * Determine if the input string matches the syntax defined by
	 * this expression. If the expression cannot be matched, an
	 * exception will be thrown.
	 *
	 * @param raw Candidate expression string.
	 *
	 * @throws IllegalArgumentExpression if the string is not a
	 * valid expression of this type.
	 */
	static Expression valueOf(String raw) throws IllegalArgumentException
	{
		KExpression exp = null;
		Matcher m = pattern.matcher(raw);

		if (m.matches()) {
			long imp = 1;

			if (m.group(2) != null)
				imp = validateImportance(m.group(2));

			validateKeyword(keys, m.group(3));
			exp = new KExpression(imp, m.group(3));
		}
		return (exp);
	}

	/**
	 * Return a string representation of this expresssion.
	 */
	public String toString()
	{
		return ("(" + getImportance() + ", " + getName() + ")");
	}

	/**
	 * Indicates whether some other KExpression is "equal to
	 * this one.
	 * @param o the reference object with which to compare.
	 * @return <code>true</code> if this object is the same as the
	 * o argument; <code>false</code> otherwise.
	 * @see	#hashCode()
	 */
	public boolean equals(Object o)
	{
		if (o == this)
			return (true);
		if (!(o instanceof KExpression))
			return (false);
		KExpression other = (KExpression) o;
		if (getName().compareTo(other.getName()) != 0)
			return (false);
		return (true);
	}

	/**
	 * Returns a hash code value for the object. This method is
	 * supported for the benefit of hashtables such as those provided by
	 * <code>java.util.Hashtable</code>.
	 *
	 * @return a hash code value for this object.
	 * @see	#equals(java.lang.Object)
	 * @see	java.util.Hashtable
	 */
	public int hashCode()
	{
		return (getName().hashCode());
	}

	/**
	 * Return true if the supplied expression "contradicts" this
	 * expression. If the supplied expression is not of the same
	 * type, then it cannot contradict it. If the names are
	 * different then there can be no contradiction.
	 *
	 * @param o Expression to examine for contradiction.
	 */
	public boolean contradicts(Expression o)
	{
		if (!(o instanceof KExpression))
			return (false);
		KExpression other = (KExpression) o;
		if (getName().compareTo(other.getName()) != 0)
			return (false);
		return (true);
	}
}