com.jacob.com

## Class ROT

- java.lang.Object
- - com.jacob.com.ROT

-     public abstract class ROT
      extends java.lang.Object

  The Running Object Table (ROT) maps each thread to a collection of all the JacobObjects that were created in that thread. It always operates on the current thread so all the methods are static and they implicitly get the current thread.

  The clearObjects method is used to release all the COM objects created by Jacob in the current thread prior to uninitializing COM for that thread.

  Prior to 1.9, manual garbage collection was the only option in Jacob, but from 1.9 onward, setting the com.jacob.autogc system property allows the objects referenced by the ROT to be automatically GCed. Automatic GC may be preferable in systems with heavy event callbacks.

  Is [ 1116101 ] jacob-msg 0284 relevant???

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.lang.Boolean` | `INCLUDE_ALL_CLASSES_IN_ROT` If the code is ran from an applet that is called from javascript the Java Plugin does not give full permissions to the code and thus System properties cannot be accessed.
    `protected static java.lang.String` | `PUT_IN_ROT_SUFFIX` Suffix added to class name to make up property name that determines if this object should be stored in the ROT.
    `protected static boolean` | `USE_AUTOMATIC_GARBAGE_COLLECTION` Manual garbage collection was the only option pre 1.9 Can staticly cache the results because only one value and we don't let it change during a run

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ROT()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static void` | `addObject(JacobObject o)` Adds an object to the HashMap for the current thread.
    `protected static java.util.Map<JacobObject,java.lang.String>` | `addThread()` adds a new thread storage area to rot
    `protected static void` | `clearObjects()` Iterates across all of the entries in the Hashmap in the rot that corresponds to this thread.
    `protected static java.util.Map<JacobObject,java.lang.String>` | `getThreadObjects(boolean createIfDoesNotExist)` Returns the pool for this thread if it exists.
    `protected static void` | `removeObject(JacobObject o)` Deprecated. the java model leave the responsibility of clearing up objects to the Garbage Collector. Our programming model should not require that the user specifically remove object from the thread. This will remove an object from the ROT This does not need to be synchronized because only the rot modification related methods need to synchronized. Each individual map is only modified in a single thread.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### USE_AUTOMATIC_GARBAGE_COLLECTION

          protected static final boolean USE_AUTOMATIC_GARBAGE_COLLECTION

      Manual garbage collection was the only option pre 1.9 Can staticly cache the results because only one value and we don't let it change during a run

    - #### INCLUDE_ALL_CLASSES_IN_ROT

          protected static final java.lang.Boolean INCLUDE_ALL_CLASSES_IN_ROT

      If the code is ran from an applet that is called from javascript the Java Plugin does not give full permissions to the code and thus System properties cannot be accessed. They can be accessed at class initialization time. The default behavior is to include all classes in the ROT, setting a boolean here to indicate this prevents a call to System.getProperty as part of the general call flow.

    - #### PUT_IN_ROT_SUFFIX

          protected static java.lang.String PUT_IN_ROT_SUFFIX

      Suffix added to class name to make up property name that determines if this object should be stored in the ROT. This 1.13 "feature" makes it possible to cause VariantViaEvent objects to not be added to the ROT in event callbacks.

      We don't have a static for the actual property because there is a different property for each class that may make use of this feature.

  - ### Constructor Detail

    - #### ROT

          public ROT()

  - ### Method Detail

    - #### addThread

          protected static java.util.Map<JacobObject,java.lang.String> addThread()

      adds a new thread storage area to rot
      Returns:
        Map corresponding to the thread that this call was made in

    - #### getThreadObjects

          protected static java.util.Map<JacobObject,java.lang.String> getThreadObjects(boolean createIfDoesNotExist)

      Returns the pool for this thread if it exists. can create a new one if you wish by passing in TRUE
      Parameters:
        `createIfDoesNotExist` -
      Returns:
        Map the collection that holds the objects created in the current thread

    - #### clearObjects

          protected static void clearObjects()

      Iterates across all of the entries in the Hashmap in the rot that corresponds to this thread. This calls safeRelease() on each entry and then clears the map when done and removes it from the rot. All traces of this thread's objects will disappear. This is called by COMThread in the tear down and provides a synchronous way of releasing memory

    - #### removeObject

          @Deprecated
          protected static void removeObject(JacobObject o)

      Deprecated. the java model leave the responsibility of clearing up objects to the Garbage Collector. Our programming model should not require that the user specifically remove object from the thread.
      This will remove an object from the ROT
      This does not need to be synchronized because only the rot modification related methods need to synchronized. Each individual map is only modified in a single thread.
      Parameters:
        `o` -

    - #### addObject

          protected static void addObject(JacobObject o)

      Adds an object to the HashMap for the current thread.

      This method does not need to be threaded because the only concurrent modification risk is on the hash map that contains all of the thread related hash maps. The individual thread related maps are only used on a per thread basis so there isn't a locking issue.

      In addition, this method cannot be threaded because it calls ComThread.InitMTA. The ComThread object has some methods that call ROT so we could end up deadlocked. This method should be safe without the synchronization because the ROT works on per thread basis and the methods that add threads and remove thread related entries are all synchronized

      Parameters:
        `o` -

http://jacob-project.sourceforge.net