gishur.x2.core
Class XObject

java.lang.Object
  |
  +--gishur.x2.core.XObject
All Implemented Interfaces:
java.lang.Cloneable, Cloneable, java.io.Serializable
Direct Known Subclasses:
XIntersectableObject, XPoint

public abstract class XObject
extends java.lang.Object
implements Cloneable, java.io.Serializable

A generic planar object. A concrete planar object should represent some sort of a planar primitive like point, line, polygon.

An XObject instance would occupy only two bytes for storing an object state. Every bit of the state variable represents one state; three bits are reserved for the internal states STATE_MUTABLE, STATE_DIRTY and STATE_LOCKED, the other 5 bits are free for specific states of the subclasses. One can check states through checkState(short) and set and clear non-internal states using setState(short) and clearState(short).

Planar object could treated as constant or modifyable. Per default planar objects are constant, represented by not setting the STATE_MUTABLE state. To ensure, that this semantic of (im)mutability is valid, every subclass should call modify() before changing its geometric data. If planar objects are mutable, the dirty state is set when modify() is called. If a planar object is locked through lock(), it prevents other threads modifying its geometric data (through modify()) until unlock() removes that lock. All this state changes should be called recursiv for all contained XObjects (e.g. for all points of a polygon). This is assured by the methods lock(), unlock(), clearDirty(), makeMutable() and makeImmutable() through getXObjectMembers().

All planar objects should implement transform enabling affine transformations. XObject provides some shortcut methods like scale(gishur.x2.core.XPoint, double, double), rotate(gishur.x2.core.XPoint, double) and translate for special affine transformations

Version:
1.0
Author:
Thomas Wolf
See Also:
Serialized Form

Field Summary
static short RESERVED_STATE_MAX_MASK
          State mask constant used for internal states.
static short STATE_DIRTY
          Dirty State.
static short STATE_LOCKED
          Locked State.
static short STATE_MUTABLE
          Mutable State.
 
Constructor Summary
XObject()
           
 
Method Summary
 boolean checkState(short state)
          Checks if the given state is set.
 boolean checkStateCleared(short state)
          Checks if the given state is cleared; that means every bit of the given state is cleared.
 void clearDirty()
          Clears the dirty state.
protected  void clearState(short state)
          Clears a given state.
 java.lang.Object clone()
          Creates a new object of the same class as this object.
 XObject copy()
          This method creates a clone of this object instance like clone with a little difference: if this is immutable, the clone won't be till the first modification.
 boolean dirty()
          Checks, if this XObject is dirty.
 XObject getMutable()
          This method returns either this XObject or a temporary mutable clone of this XObject, depending on its mutability.
 java.lang.Object getOldXObject()
          Returns corresponding old gishur.x-object.
protected abstract  XObject[] getXObjectMembers()
          This method should return all XObject members that contain geometric information.
 XObject inverseTransform(double m00, double m01, double m02, double m10, double m11, double m12)
          Inverse transforms this XObject by the given affine transformation matrix.
 void lock()
          Sets the write-lock on this XObject.
 boolean locked()
          Returns true, if the XObject is locked.
protected  void makeImmutable()
          Makes this object immutable.
protected  void makeMutable()
          Makes this object mutable.
protected  void modify()
          This method should only be called from this XObject, if its instance variables should be modified.
 boolean mutable()
          Checks, if this XObject is mutable.
 void restoreMutability()
          Restores the mutability information to the information of the original of this clone.
 XObject rotate(XPoint center, double angle)
          Rotates this XObject around the rotation center center by angle.
 XObject scale(XPoint center, double xscale, double yscale)
          Scales this XObject with xscale and yscale scale factors and with center point center.
protected  void setState(short state)
          Sets a given state.
protected  short state()
          Returns the complete state of this XObject.
protected  short state(short state)
          Returns the state for the given state constant.
 java.lang.String toString_complete()
          Returns a more detailed string representation of the object than toString().
 java.lang.String toString_state()
          Returns a String representation of the internal XObject state.
 java.lang.String toString()
          Returns a string representation of the object.
 XObject transform(AffineTransformation t)
          Transforms this XObject by the given affine transformation matrix.
abstract  XObject transform(double m00, double m01, double m02, double m10, double m11, double m12)
          Transforms this XObject by the given affine transformation matrix.
 XObject translate(double dx, double dy)
          Translates this XObject by the given Vector (dx,dy).
 XObject translate(XPoint v)
          Translates this XObject by the given Vector v.
 void unlock()
          Removes the write-lock on this XObject.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STATE_MUTABLE

public static final short STATE_MUTABLE
Mutable State. XObjects which are mutable can modified.

STATE_DIRTY

public static final short STATE_DIRTY
Dirty State. XObjects which are dirty were modified since last call of clearDirty().

STATE_LOCKED

public static final short STATE_LOCKED
Locked State. XObjects which are locked cannot be modified unless the lock is removed. All modifying operations have to wait till this happens.

RESERVED_STATE_MAX_MASK

public static final short RESERVED_STATE_MAX_MASK
State mask constant used for internal states. Every user state must use other bits than this constant (=0x000f), otherwise (parts of) the user state constants will be ignored.
Constructor Detail

XObject

public XObject()
Method Detail

checkState

public final boolean checkState(short state)
Checks if the given state is set.
Parameters:
state - state to verify
Returns:
True, if state set, else false.

checkStateCleared

public final boolean checkStateCleared(short state)
Checks if the given state is cleared; that means every bit of the given state is cleared.
Parameters:
state - state to verify
Returns:
True, if state cleared, else false.

state

protected final short state()
Returns the complete state of this XObject.
Returns:
State.

state

protected final short state(short state)
Returns the state for the given state constant.
Returns:
State information.

setState

protected final void setState(short state)
Sets a given state. state must use other bits than RESERVED_STATE_MAX_MASK, otherwise these bits will be ignored.
Parameters:
state - state to set

clearState

protected final void clearState(short state)
Clears a given state. state must use other bits than RESERVED_STATE_MAX_MASK, otherwise these bits will be ignored.
Parameters:
state - state to clear

mutable

public boolean mutable()
Checks, if this XObject is mutable.
Returns:
true, if mutable (STATE_MUTABLE is set)

makeMutable

protected void makeMutable()
Makes this object mutable. This means this Object can modify its coordinates (and some other geometric information). This must be assured by every subclass of XObject itself. makeMutable() will not be called for XObject members. makeMutable() may be overriden with public modifier to make it accessible for all classes, but should finally call this method implementation.

makeImmutable

protected void makeImmutable()
Makes this object immutable. This means this Object cannot modify its coordinates (and some other geometric information). This must be assured by every subclass of XObject itself. makeImmutable() will not be called for XObject members. makeImmutable() may be overriden with public modifier to make it accessible for all classes, but should finally call this method implementation.

dirty

public final boolean dirty()
Checks, if this XObject is dirty. An XObject will become dirty, if its data changed. So immutable XObjects will become dirty only once - at construction time.
Returns:
true, if dirty (STATE_DIRTY is set)

clearDirty

public final void clearDirty()
Clears the dirty state. Propagation to all contained XObjects is assured through getXObjectMembers().

locked

public final boolean locked()
Returns true, if the XObject is locked.
Returns:
true, if locked (STATE_LOCKED is set)

lock

public final void lock()
Sets the write-lock on this XObject. That means any modifying method should block until the write lock is removed. Propagation to all contained XObjects is assured through getXObjectMembers().
See Also:
unlock()

unlock

public final void unlock()
Removes the write-lock on this XObject. That means all waiting modifying methods wakeup. Propagation to all contained XObjects is assured through getXObjectMembers().
See Also:
unlock()

modify

protected final void modify()
This method should only be called from this XObject, if its instance variables should be modified. If it is immutable, then an GeomException will be thrown, otherwise it waits, till there is no lock set and set the dirty state. There must be exactly one call of modify before a modification!
Throws:
GeomException - if XObject is immutable

getXObjectMembers

protected abstract XObject[] getXObjectMembers()
This method should return all XObject members that contain geometric information. The result will be used by makeMutable(), makeImmutable(), clearDirty(), lock() and unlock(). To make this work there must not occur circular dependencies.
Returns:
Array with all XObject members (or null if none).

transform

public abstract XObject transform(double m00,
                                  double m01,
                                  double m02,
                                  double m10,
                                  double m11,
                                  double m12)
Transforms this XObject by the given affine transformation matrix.
Parameters:
m00,m01,m02 - first row of the transformation matrix
m10,m11,m12 - second row of the transformation matrix
Returns:
Transformed XObject (this, only if it is mutable, otherwise a new XObject represeting the transformed object).

inverseTransform

public XObject inverseTransform(double m00,
                                double m01,
                                double m02,
                                double m10,
                                double m11,
                                double m12)
Inverse transforms this XObject by the given affine transformation matrix.
Parameters:
m00,m01,m02 - first row of the transformation matrix
m10,m11,m12 - second row of the transformation matrix
Returns:
Inverse transformed XObject (this, only if it is mutable, otherwise a new XObject represeting the transformed object).

transform

public XObject transform(AffineTransformation t)
Transforms this XObject by the given affine transformation matrix.
Parameters:
t - the transformation matrix
Returns:
Transformed XObject (this, only if it is mutable)

scale

public XObject scale(XPoint center,
                     double xscale,
                     double yscale)
Scales this XObject with xscale and yscale scale factors and with center point center.
Parameters:
center - immutable scaling center point
xscale - scale factor for x-axis
yscale - scale factor for y-axis
Returns:
transformed XObject (this, only if it is mutable)

rotate

public XObject rotate(XPoint center,
                      double angle)
Rotates this XObject around the rotation center center by angle.
Parameters:
center - rotation center
angle - rotation angle
Returns:
transformed XObject (this, only if it is mutable)

translate

public XObject translate(double dx,
                         double dy)
Translates this XObject by the given Vector (dx,dy).
Parameters:
(dx,dy) - translation vector
Returns:
transformed XObject (this, only if it is mutable)

translate

public XObject translate(XPoint v)
Translates this XObject by the given Vector v.
Parameters:
(dx,dy) - translation vector
Returns:
transformed XObject (this, only if it is mutable)

clone

public java.lang.Object clone()
Creates a new object of the same class as this object.
Specified by:
clone in interface Cloneable
Overrides:
clone in class java.lang.Object
Returns:
a clone of this instance.
Throws:
OutOfMemoryError - if there is not enough memory.
See Also:
Cloneable

copy

public XObject copy()
This method creates a clone of this object instance like clone with a little difference: if this is immutable, the clone won't be till the first modification. This is usefull if you like to create a modified version of an object instance and you don't know, if this object is mutable. With copy you can assure, there will be created a new instance; you can write code as this:
XObject a=...;
 XObject b=a.copy().translate(x,y);
If a is mutable, copy assures that a new instance is created and translate(double, double) works on that copy. If a is immutable, copy creates a new instance of a and lets modify translate(double, double) this instance exactly one time.
Returns:
Clone of this object, that is modifyable at least one time (depending on the immutable-flag of this).

getMutable

public XObject getMutable()
This method returns either this XObject or a temporary mutable clone of this XObject, depending on its mutability. If this XObject is immutable, a clone will be created and returned that is mutable until a call to restoreMutability(). This gives one the possibility to write code like this without knowing something about the mutability of the used XObject:
XObject a=...;
 a=getMutable();         // get a mutable version of a
 a.transform(...);       // change a
 ... (can be more transformations)
 a.restoreMutability();  // restore the old mutability information of the original
 
Returns:
either this or a mutable clone.
See Also:
copy(), #restorMutability

restoreMutability

public void restoreMutability()
Restores the mutability information to the information of the original of this clone. If this is a normal mutable (or immutable) XObject, nothing happens.

toString

public java.lang.String toString()
Returns a string representation of the object.
Overrides:
toString in class java.lang.Object
Returns:
a string representation of the object.

toString_complete

public java.lang.String toString_complete()
Returns a more detailed string representation of the object than toString().
Returns:
a string representation of the object.

toString_state

public java.lang.String toString_state()
Returns a String representation of the internal XObject state.
Returns:
a string representation of the XObject state.

getOldXObject

public java.lang.Object getOldXObject()
Returns corresponding old gishur.x-object.
Returns:
Corresponding old gishur.x-object.