CanonicalWatched

java.lang.Object
- buffer.CanonicalWatched

Direct Known Subclasses:

SDD, SDDTree, SDDTreeConjunction, Vtree
```
public abstract class CanonicalWatched
extends java.lang.Object
```
A CanonicalWatched, i.e., a canonical watched, is an object that is canonical, i.e., such that no two equal elements can be instantiated. The canonical watched are stored in a map. In order to know when they may be removed from the storage, they need to be watched, i.e., any outside reference to the object must be indicated through methods watch() and unwatch(). The method that decides whether two canonical watched are equal (and, therefore, one should be removed), is equivalent(java.lang.Object).
Implementations of CanonicalWatched should not allow for public constructor. Instead, it is recommended to have a method called create and whose skeleton is the following: public static X create(Object[] params) { final X x = new X(params); final X canon = x.getCanonical(); if (canon == x) { // this is the first instantiation of the object // finish initialising (stuff that was not required for #equivalent(Object) } canon.watch(); return canon; }

Constructor Summary

Constructors
Constructor and Description

CanonicalWatched()

Constructors
Constructor and Description
`CanonicalWatched()`

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`destroy()` Notifies this object that it is no longer referenced.
`boolean`	`equals(java.lang.Object obj)` Indicates whether this object equals the specified object.
`protected abstract boolean`	`equivalent(java.lang.Object obj)` Indicates whether the specified object is equivalent to this object.
`protected abstract <K extends CanonicalWatched> java.util.Map<java.lang.Object,K>`	`getBuffer()` Returns the buffer that is used to decide the canonical objects.
`protected <K extends CanonicalWatched> K`	`getCanonical()` Returns the canonical version of this object.
`abstract int`	`hashCode()`
`void`	`print(java.io.PrintStream out)` Prints out the buffer.
`<K extends CanonicalWatched> void`	`unwatch()` Notifies this object that an external component no longer uses this object.
`static void`	`unwatchAll(java.util.Collection<? extends CanonicalWatched> coll)` Unwatches all the elements in the specified collection of canonical watched objects.
`void`	`verifyValidity()` Verifies that the number of watches of this object is over 0.
`void`	`watch()` Notifies this object that it is used by an external component of the software.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CanonicalWatched
```
public CanonicalWatched()
```
- Method Detail
  - watch
```
public final void watch()
```
    Notifies this object that it is used by an external component of the software.
  - unwatch
```
public final <K extends CanonicalWatched> void unwatch()
```
    Notifies this object that an external component no longer uses this object.
  - equals
```
public final boolean equals(java.lang.Object obj)
```
    Indicates whether this object equals the specified object. Because the objects are canonical, equality is defined by references. The method used to verify whether a new instance of the object equals an existing instance (i.e., before canonicity has been decided), is equivalent(Object).
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    obj - the object to compare to this.
    
    Returns:
    true if this == obj.
  - hashCode
```
public abstract int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - getCanonical
```
protected final <K extends CanonicalWatched> K getCanonical()
```
    Returns the canonical version of this object. If there exists an object in memory that is equivalent to this object (through method equivalent(Object)), then that object is returned. Otherwise, this object is returned.
    
    Returns:
    the canonical version of this.
  - destroy
```
protected void destroy()
```
    Notifies this object that it is no longer referenced. The object may have some cleaning up to do at this stage. The default implementation is that the object does nothing.
  - equivalent
```
protected abstract boolean equivalent(java.lang.Object obj)
```
    Indicates whether the specified object is equivalent to this object. There should not be two equivalent objects, so this method is used at the creation of this type of object to verify whether the object create is truly original.
    
    Parameters:
    obj - the object compared to this object.
    
    Returns:
    true if obj is equivalent to this.
  - getBuffer
```
protected abstract <K extends CanonicalWatched> java.util.Map<java.lang.Object,K> getBuffer()
```
    Returns the buffer that is used to decide the canonical objects.
    
    Returns:
    a map that contains the canonical objects.
  - print
```
public void print(java.io.PrintStream out)
```
    Prints out the buffer. This is a debug method.
    
    Parameters:
    out - the output where the buffer is printed.
  - unwatchAll
```
public static void unwatchAll(java.util.Collection<? extends CanonicalWatched> coll)
```
    Unwatches all the elements in the specified collection of canonical watched objects. If an object is present more than once, it is unwatched several times. null objects can also appear in the collection. This method is often used before the collection is discarded.
    
    Parameters:
    coll - the collection of objects that must be unwatched.
  - verifyValidity
```
public void verifyValidity()
```
    Verifies that the number of watches of this object is over 0. This is for debug only.
    
    Throws:
    
    java.lang.IllegalStateException - if the number of watches is 0.

Class CanonicalWatched

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CanonicalWatched

Method Detail

watch

unwatch

equals

hashCode

getCanonical

destroy

equivalent

getBuffer

print

unwatchAll

verifyValidity