/**
* Returns whether <code>equals</code> rather than <code>==</code> should be used to compare members.
* The default is to return <code>true</code> but clients can optimize performance by returning <code>false</code>.
* The performance difference is highly significant.
* @return whether <code>equals</code> rather than <code>==</code> should be used.
*/
protected boolean useEquals() {
return true;
}
/**
* Returns whether two objects are equal using the {@link #useEquals appropriate} comparison mechanism.
* @return whether two objects are equal.
*/
protected boolean equalObjects(Object firstObject, Object secondObject) {
return useEquals() && firstObject != null ? firstObject.equals(secondObject): firstObject == secondObject;
}
/**
* Returns whether <code>null</code> is a valid object for the list.
* The default is to return <code>true</code>, but clients can override this to exclude <code>null</code>.
* @return whether <code>null</code> is a valid object for the list.
*/
protected boolean canContainNull() {
return true;
}
/**
* Returns whether objects are constrained to appear at most once in the list.
* The default is to return <code>false</code>, but clients can override this to ensure uniqueness of contents.
* The performance impact is significant: operations such as <code>add</code> are O(n) as a result requiring uniqueness.
* @return whether objects are constrained to appear at most once in the list.
*/
protected boolean isUnique() {
return false;
}
/**
* Validates a new content object and returns the validated object.
* This implementation checks for null, if {@link #canContainNull necessary} and returns the argument object.
* Clients may throw additional types of runtime exceptions
* in order to handle constraint violations.
* @param index the position of the new content.
* @param object the new content.
* @return the validated content.
* @exception IllegalArgumentException if a constraint prevents the object from being added.
*/
protected E validate(int index, E object) {
if ( !canContainNull() && object == null) {
throw new IllegalArgumentException("The \'no null\' constraint is violated");
}
return object;
}
|