net.jini.core.constraint
Class InvocationConstraints

java.lang.Object
  extended by net.jini.core.constraint.InvocationConstraints
All Implemented Interfaces:
Serializable

public final class InvocationConstraints
extends Object
implements Serializable

An immutable aggregation of constraints into a set of requirements and a set of preferences. A requirement is a mandatory constraint that must be satisfied for the invocation. A preference is a desired constraint, to be satisfied if possible, but it will not be satisfied if it conflicts with a requirement. If two preferences conflict, it is arbitrary as to which one will be satisfied. If a constraint is not understood, due to lack of knowledge of the type of the constraint or the contents of the constraint, then the constraint cannot be satisfied.

Note that it is possible for an instance of this class to contain both requirements that conflict with each other, and preferences that conflict with each other and with requirements.

Since:
2.0
Author:
Sun Microsystems, Inc.
See Also:
Serialized Form

Field Summary
private static InvocationConstraint[] empty
          An empty array
static InvocationConstraints EMPTY
          An empty instance, one that has no requirements and no preferences.
private  InvocationConstraint[] prefs
          The preferences.
private  int rel
          Flags indicating whether any requirements and/or preferences are based on relative time.
private static int REL_PREFS
          Bit set in the rel field if there are relative preferences.
private static int REL_REQS
          Bit set in the rel field if there are relative requirements.
private  InvocationConstraint[] reqs
          The requirements.
private static ObjectStreamField[] serialPersistentFields
           
private static long serialVersionUID
           
 
Constructor Summary
  InvocationConstraints(Collection reqs, Collection prefs)
          Creates an instance that has all of the constraints from the first collection, reqs, added as requirements if the collection is a non-null value, and has all of the constraints from the second collection, prefs, added as preferences if the collection is a non-null value.
private InvocationConstraints(InvocationConstraint[] reqs, int reqidx, InvocationConstraint[] prefs, int prefidx, int rel)
          Creates an instance containing the specified requirements and preferences.
  InvocationConstraints(InvocationConstraint[] reqs, InvocationConstraint[] prefs)
          Creates an instance that has all of the constraints from the first array, reqs, added as requirements if the array is a non-null value, and has all of the constraints from the second array, prefs, added as preferences if the array is a non-null value.
  InvocationConstraints(InvocationConstraint req, InvocationConstraint pref)
          Creates an instance that has the first constraint, req, added as a requirement if it is a non-null value, and has the second constraint, pref, added as a preference if it is a non-null value and is not a duplicate of the requirement.
 
Method Summary
static InvocationConstraints combine(InvocationConstraints constraints1, InvocationConstraints constraints2)
          Returns an instance of this class that has all of the requirements from each non-null argument added as requirements and has all of the preferences from each non-null argument added as preferences.
private static InvocationConstraint[] concat(InvocationConstraint[] arr1, InvocationConstraint[] arr2)
          Returns a new array containing the elements of both arguments.
 boolean equals(Object obj)
          Two instances of this class are equal if they have the same requirements and the same preferences.
 int hashCode()
          Returns a hash code value for this object.
 boolean isEmpty()
          Returns true if the instance has no requirements and no preferences; returns false otherwise.
 InvocationConstraints makeAbsolute()
          Returns an instance of this class constructed from all of the same requirements and preferences as this instance, but with every constraint that is an instance of RelativeTimeConstraint replaced by the result of invoking the constraint's makeAbsolute method with the current time (as given by System.currentTimeMillis).
private static InvocationConstraint[] makeAbsolute(InvocationConstraint[] arr, long baseTime)
          Converts any relative constraints to absolute time.
 InvocationConstraints makeAbsolute(long baseTime)
          Returns an instance of this class equal to the result of taking the requirements and preferences in this instance, replacing each constraint that is an instance of RelativeTimeConstraint with the result of invoking that constraint's makeAbsolute method with the specified base time, and creating a new instance of this class with duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements all removed.
 Set preferences()
          Returns an immutable set of all of the preferences.
private  void readObject(ObjectInputStream s)
          Verifies that there are no null elements and no duplicates.
private  void reduce()
          Replaces null fields with empty arrays, eliminates duplicates, and sets flags indicating which constraints are relative.
private  void reduce(int reqidx, int prefidx)
          Checks for nulls and eliminates duplicates.
private static boolean relative(InvocationConstraint c)
          Returns true if the specified constraint either implements RelativeTimeConstraint or is an instance of ConstraintAlternatives with elements that implement RelativeTimeConstraint, and false otherwise.
 Set requirements()
          Returns an immutable set of all of the requirements.
private  void setRelative(InvocationConstraint[] constraints, int flag)
          Sets the given flag in the rel field if any if the specified constraints are relative.
 String toString()
          Returns a string representation of this object.
private static void verify(InvocationConstraint[] constraints)
          Verifies that the array is non-null, the elements are all non-null, and there are no duplicates.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

serialPersistentFields

private static final ObjectStreamField[] serialPersistentFields

empty

private static final InvocationConstraint[] empty
An empty array


REL_REQS

private static final int REL_REQS
Bit set in the rel field if there are relative requirements.

See Also:
Constant Field Values

REL_PREFS

private static final int REL_PREFS
Bit set in the rel field if there are relative preferences.

See Also:
Constant Field Values

EMPTY

public static final InvocationConstraints EMPTY
An empty instance, one that has no requirements and no preferences.


reqs

private InvocationConstraint[] reqs
The requirements.


prefs

private InvocationConstraint[] prefs
The preferences.


rel

private transient int rel
Flags indicating whether any requirements and/or preferences are based on relative time.

Constructor Detail

InvocationConstraints

public InvocationConstraints(InvocationConstraint req,
                             InvocationConstraint pref)
Creates an instance that has the first constraint, req, added as a requirement if it is a non-null value, and has the second constraint, pref, added as a preference if it is a non-null value and is not a duplicate of the requirement.

Parameters:
req - a requirement, or null
pref - a preference, or null

InvocationConstraints

public InvocationConstraints(InvocationConstraint[] reqs,
                             InvocationConstraint[] prefs)
Creates an instance that has all of the constraints from the first array, reqs, added as requirements if the array is a non-null value, and has all of the constraints from the second array, prefs, added as preferences if the array is a non-null value. Duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements are all removed. The arguments passed to the constructor are neither modified nor retained; subsequent changes to those arguments have no effect on the instance created.

Parameters:
reqs - requirements, or null
prefs - preferences, or null
Throws:
NullPointerException - if any element of an argument is null

InvocationConstraints

public InvocationConstraints(Collection reqs,
                             Collection prefs)
Creates an instance that has all of the constraints from the first collection, reqs, added as requirements if the collection is a non-null value, and has all of the constraints from the second collection, prefs, added as preferences if the collection is a non-null value. Duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements are all removed. The arguments passed to the constructor are neither modified nor retained; subsequent changes to those arguments have no effect on the instance created.

Parameters:
reqs - requirements, or null
prefs - preferences, or null
Throws:
NullPointerException - if any element of an argument is null
IllegalArgumentException - if any element of an argument is not an instance of InvocationConstraint

InvocationConstraints

private InvocationConstraints(InvocationConstraint[] reqs,
                              int reqidx,
                              InvocationConstraint[] prefs,
                              int prefidx,
                              int rel)
Creates an instance containing the specified requirements and preferences. Reqidx and prefidx indicate how many of the initial elements in each array are known to have been reduced (meaning they came from an existing instance of this class), but prefidx must be zero if reqidx is non-zero but reqidx is less than the total number of requirements. Rel contains the flags for which constraints are relative.

Method Detail

reduce

private void reduce()
Replaces null fields with empty arrays, eliminates duplicates, and sets flags indicating which constraints are relative.


reduce

private void reduce(int reqidx,
                    int prefidx)
Checks for nulls and eliminates duplicates. Reqidx and prefidx indicate how many of the initial elements in each array are known to have been reduced (meaning they came from an existing instance of this class), but prefidx must be zero if reqidx is non-zero but reqidx is less than the total number of requirements.


relative

private static boolean relative(InvocationConstraint c)
Returns true if the specified constraint either implements RelativeTimeConstraint or is an instance of ConstraintAlternatives with elements that implement RelativeTimeConstraint, and false otherwise.


setRelative

private void setRelative(InvocationConstraint[] constraints,
                         int flag)
Sets the given flag in the rel field if any if the specified constraints are relative.


combine

public static InvocationConstraints combine(InvocationConstraints constraints1,
                                            InvocationConstraints constraints2)
Returns an instance of this class that has all of the requirements from each non-null argument added as requirements and has all of the preferences from each non-null argument added as preferences. Duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements are all removed.

Parameters:
constraints1 - constraints, or null
constraints2 - constraints, or null
Returns:
an instance of this class that has all of the requirements from each non-null argument added as requirements and has all of the preferences from each non-null argument added as preferences

concat

private static InvocationConstraint[] concat(InvocationConstraint[] arr1,
                                             InvocationConstraint[] arr2)
Returns a new array containing the elements of both arguments.


makeAbsolute

private static InvocationConstraint[] makeAbsolute(InvocationConstraint[] arr,
                                                   long baseTime)
Converts any relative constraints to absolute time.


makeAbsolute

public InvocationConstraints makeAbsolute(long baseTime)
Returns an instance of this class equal to the result of taking the requirements and preferences in this instance, replacing each constraint that is an instance of RelativeTimeConstraint with the result of invoking that constraint's makeAbsolute method with the specified base time, and creating a new instance of this class with duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements all removed.

Parameters:
baseTime - an absolute time, specified in milliseconds from midnight, January 1, 1970 UTC
Returns:
an instance of this class equal to the result of taking the requirements and preferences in this instance, replacing each constraint that is an instance of RelativeTimeConstraint with the result of invoking that constraint's makeAbsolute method with the specified base time, and creating a new instance of this class with duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements all removed

makeAbsolute

public InvocationConstraints makeAbsolute()
Returns an instance of this class constructed from all of the same requirements and preferences as this instance, but with every constraint that is an instance of RelativeTimeConstraint replaced by the result of invoking the constraint's makeAbsolute method with the current time (as given by System.currentTimeMillis). Duplicate requirements, duplicate preferences, and preferences that are duplicates of requirements are all removed.

Returns:
an instance of this class constructed from all of the same requirements and preferences as this instance, but with every constraint that is an instance of RelativeTimeConstraint replaced by the result of invoking the constraint's makeAbsolute method with the current time

requirements

public Set requirements()
Returns an immutable set of all of the requirements. Any attempt to modify this set results in an UnsupportedOperationException being thrown.

Returns:
an immutable set of all of the requirements

preferences

public Set preferences()
Returns an immutable set of all of the preferences. Any attempt to modify this set results in an UnsupportedOperationException being thrown.

Returns:
an immutable set of all of the preferences

isEmpty

public boolean isEmpty()
Returns true if the instance has no requirements and no preferences; returns false otherwise.

Returns:
true if the instance has no requirements and no preferences; false otherwise

hashCode

public int hashCode()
Returns a hash code value for this object.

Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)
Two instances of this class are equal if they have the same requirements and the same preferences. This method is a sufficient substitute for TrustEquivalence.checkTrustEquivalence.

Overrides:
equals in class Object

toString

public String toString()
Returns a string representation of this object.

Overrides:
toString in class Object

readObject

private void readObject(ObjectInputStream s)
                 throws IOException,
                        ClassNotFoundException
Verifies that there are no null elements and no duplicates.

Throws:
InvalidObjectException - if the requirements or preferences arrays are null, or any element is null, or if there are duplicate requirements, duplicate preferences, or preferences that are duplicates of requirements
IOException
ClassNotFoundException

verify

private static void verify(InvocationConstraint[] constraints)
                    throws InvalidObjectException
Verifies that the array is non-null, the elements are all non-null, and there are no duplicates.

Throws:
InvalidObjectException


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.