Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# Object Class Reference

`#include <coherence/lang/Object.hpp>`

Inherited by AbstractEvolvable `[virtual]`, AbstractReadBuffer `[virtual]`, AbstractReadBuffer::AbstractBufferInput `[virtual]`, AbstractWriteBuffer `[virtual]`, AbstractWriteBuffer::AbstractBufferOutput `[virtual]`, Evolvable `[virtual]`, PofConstants `[virtual]`, PofHandler `[virtual]`, PofReader `[virtual]`, PofSerializer `[virtual]`, PofWriter `[virtual]`, PortableObject `[virtual]`, PortableObjectSerializer `[virtual]`, PrincipalPofSerializer `[virtual]`, RawDate `[virtual]`, RawDateTime `[virtual]`, RawDayTimeInterval `[virtual]`, RawTime `[virtual]`, RawTimeInterval `[virtual]`, RawYearMonthInterval `[virtual]`, ReferenceLibrary `[virtual]`, AbstractPofPath `[virtual]`, PofNavigator `[virtual]`, PofValue `[virtual]`, SimplePofContext `[virtual]`, SubjectPofSerializer `[virtual]`, ThrowablePofSerializer `[virtual]`, TypedSerializer `[virtual]`, WritingPofHandler::Complex `[virtual]`, ReadBuffer `[virtual]`, ReadBuffer::BufferInput `[virtual]`, Serializer `[virtual]`, WrapperStreamFactory `[virtual]`, WriteBuffer `[virtual]`, WriteBuffer::BufferOutput `[virtual]`, AbstractHeapAnalyzer `[virtual]`, Array `[virtual]`, Array< bool > `[virtual]`, Array< char > `[virtual]`, Array< int32_t > `[virtual]`, Array< octet_t > `[virtual]`, Class `[virtual]`, ClassBasedHeapAnalyzer::ClassStats `[virtual]`, ClassBasedHeapAnalyzer::Snapshot `[virtual]`, ClassLoader `[virtual]`, Comparable `[virtual]`, Exception `[virtual]`, ExecutableClass `[virtual]`, extends< Object, A > `[virtual]`, extends< Object, Void< Object > > `[virtual]`, HeapAnalyzer `[virtual]`, HeapAnalyzer::Snapshot `[virtual]`, interface_spec `[virtual]`, Managed `[virtual]`, Number `[virtual]`, ObjectCountHeapAnalyzer `[virtual]`, ObjectCountHeapAnalyzer::Snapshot `[virtual]`, Primitive `[virtual]`, Primitive< bool > `[virtual]`, Primitive< char16_t > `[virtual]`, Primitive< float32_t > `[virtual]`, Primitive< float64_t > `[virtual]`, Primitive< int16_t > `[virtual]`, Primitive< int32_t > `[virtual]`, Primitive< int64_t > `[virtual]`, Primitive< octet_t > `[virtual]`, Reference `[virtual]`, Runnable `[virtual]`, StackTraceElement `[virtual]`, System `[virtual]`, System::CommonMonitor `[virtual]`, SystemClassLoader `[virtual]`, Thread `[virtual]`, ThreadGroup `[virtual]`, ThreadLocalReference `[virtual]`, WeakReference `[virtual]`, AbstractInvocable `[virtual]`, AbstractPriorityTask `[virtual]`, AddressProvider `[virtual]`, AbstractCacheLoader `[virtual]`, CacheLoader `[virtual]`, CacheStatistics `[virtual]`, ContinuousQueryCache::AsynchronousEvent `[virtual]`, ContinuousQueryCache::TaskDaemon `[virtual]`, KeyAssociation `[virtual]`, SimpleCacheStatistics `[virtual]`, UnitCalculator `[virtual]`, CacheFactory `[virtual]`, ConfigurableAddressProvider `[virtual]`, ConfigurableAddressProvider::AddressHolder `[virtual]`, DefaultConfigurableCacheFactory `[virtual]`, DefaultConfigurableCacheFactory::CacheInfo `[virtual]`, InetAddress `[virtual]`, InetSocketAddress `[virtual]`, Member `[virtual]`, PriorityTask `[virtual]`, ServiceInfo `[virtual]`, SocketAddress `[virtual]`, XmlConfigurable `[virtual]`, XmlValue `[virtual]`, GenericSubject `[virtual]`, Subject `[virtual]`, DefaultIdentityAsserter `[virtual]`, DefaultIdentityTransformer `[virtual]`, GenericPrincipal `[virtual]`, IdentityAsserter `[virtual]`, IdentityTransformer `[virtual]`, Principal `[virtual]`, EndIterator `[virtual]`, AbstractCollection `[virtual]`, AbstractConcurrentQueue `[virtual]`, AbstractLongArray `[virtual]`, AbstractMapListener `[virtual]`, AbstractSparseArray::Node `[virtual]`, AbstractStableIterator `[virtual]`, AbstractAggregator `[virtual]`, CompositeAggregator `[virtual]`, Count `[virtual]`, GroupAggregator `[virtual]`, AtomicCounter `[virtual]`, Collection `[virtual]`, Comparator `[virtual]`, ChainedComparator `[virtual]`, SafeComparator `[virtual]`, CompositeKey `[virtual]`, Controllable `[virtual]`, Converter `[virtual]`, ConverterCollections::ConverterMapListener `[virtual]`, ConverterCollections::EntryConverter `[virtual]`, ConverterCollections::UnsupportedConverter `[virtual]`, Describable `[virtual]`, Enumeration `[virtual]`, Event `[virtual]`, EventListener `[virtual]`, AbstractExtractor `[virtual]`, AbstractUpdater `[virtual]`, CompositeUpdater `[virtual]`, PofUpdater `[virtual]`, ReflectionUpdater `[virtual]`, Filter `[virtual]`, AlwaysFilter `[virtual]`, ArrayFilter `[virtual]`, ArrayFilter::WeightedFilter `[virtual]`, ExtractorFilter `[virtual]`, FilterTrigger `[virtual]`, InKeySetFilter `[virtual]`, KeyAssociatedFilter `[virtual]`, KeyFilter `[virtual]`, LikeFilter::MatchStep `[virtual]`, LimitFilter `[virtual]`, MapEventFilter `[virtual]`, MapEventTransformerFilter `[virtual]`, NeverFilter `[virtual]`, NotFilter `[virtual]`, PresentFilter `[virtual]`, FilterMuterator `[virtual]`, InvocableMap::EntryAggregator `[virtual]`, InvocableMap::EntryProcessor `[virtual]`, Iterator `[virtual]`, LinkedList::ListElement `[virtual]`, Listeners `[virtual]`, LongArray `[virtual]`, Map `[virtual]`, Map::Entry `[virtual]`, MapEventTransformer `[virtual]`, MapIndex `[virtual]`, MapKeySet::KeyConverter `[virtual]`, MapListenerSupport `[virtual]`, MapListenerSupport::WrapperSynchronousListener `[virtual]`, MapTrigger `[virtual]`, MapValuesCollection::ValueConverter `[virtual]`, MultiplexingMapListener `[virtual]`, NullFilter `[virtual]`, NullImplementation::NullCollection `[virtual]`, NullImplementation::NullMap `[virtual]`, NullImplementation::NullMuterator `[virtual]`, NullImplementation::NullValueExtractor `[virtual]`, PropertyManipulator `[virtual]`, Queue `[virtual]`, Random `[virtual]`, SafeHashMap::Entry `[virtual]`, SimpleMapIndex `[virtual]`, ThreadGate `[virtual]`, ThreadGate::Counter `[virtual]`, ExtractorEventTransformer `[virtual]`, SemiLiteEventTransformer `[virtual]`, TreeMap::Node `[virtual]`, TypedCollections::TypedMap::EntryConverter `[virtual]`, UUID `[virtual]`, ValueExtractor `[virtual]`, ValueManipulator `[virtual]`, ValueUpdater `[virtual]`, Versionable `[virtual]`, WrapperCollections::AbstractWrapperCollection `[virtual]`, WrapperCollections::AbstractWrapperEntry `[virtual]`, WrapperCollections::AbstractWrapperIterator `[virtual]`, WrapperCollections::AbstractWrapperList `[virtual]`, WrapperCollections::AbstractWrapperMap `[virtual]`, and WrapperCollections::AbstractWrapperSet `[virtual]`.

List of all members.

## Detailed Description

Object is the base class for all Coherence managed objects.

The interface for Object provides support basic operations such as equality, hashing, printing, cloning, synchronization, and notification.

Objects have automatically managed memory, through built-in thread-safe reference counting. The reference count is maintained through the use of smart-pointers, known as handles. All references to an Object should be maintained through a handle rather then a raw pointer, or C++ reference.

Each managed class includes inner definitions of handles which can be used to reference instance of that class, as well as derived class instances. These definitions provide functionality corresponding to const and non-const pointers. The names for these handles are Handle for the non-const, View for the const pointer equivalent, and Holder for a hybrid. The Holder type acts like a View but allows for a safe down-cast to a Handle, which will only succeed if the Holder was assigned from a Handle, and will fail with a ClassCastException if it had been assigned from a View. Note that in documentation the term "handle" is used to describe any handle type including Handle/View/Holder, while "Handle" refers to the specific "Handle" type.

The handles are aware of the inheritance hierarchy, allowing direct assignment from a handle from a derived class to a handle of a base class. These up-casts are automatic, and an explicit cast operation is rarely needed, except to resolve compiler type ambiguities. Assignment from a View to a Handle is also automatic as the const-interface of a class can naturally be considered a base-class. Assignment of a handle to a derived type is not automatic, and requires an explicit down-cast via the coherence cast<H>(h) function. The template parameter is the desired handle type, while the function parameter is the handle to cast. If the supplied handle is non-NULL and is not an instance of the class associated with H, a ClassCastException will be thrown. There is a corresponding instanceof<H>(h) method which can be used to perform the type-check without the risk of triggering an exception. The use of instanceof, is optional, and is only needed if the type is actually in question.

     Object::Handle hObject = ...
     Foo::Handle    hFoo;

     if (instanceof<Foo::Handle>(hObject))
       {
       hFoo = cast<Foo::Handle>(hObject);
       }

These convenience handles are not thread-safe, and should not be used in a multi-threaded context. They should only be used as local variables, though they are free to reference objects shared by many threads. The most common place where thread-safe handles are needed is for data members of managed objects. For these cases the Coherence API includes a variety of thread-safe handles/views. It is necessary that any class which extends from Object use thread-safe handles when referencing other managed Objects.

By convention managed objects will also block direct external access to their constructor and destructor. Constructors are accessed via public static "create" factory methods. The copy constructor is accessed via the public virtual "clone" method. Destructors are protected and destruction is triggered automatically when the internal reference count reaches zero.

See also:
  class_spec for defining non-cloneable classes

  cloneable_spec for defining cloneable classes

  abstract_spec for defining abstract classes

  interface_spec for defining interfaces

  throwable_spec for defining exceptions

  MemberHandle for thread-safe data member handles

  MemberView for thread-safe data member views

  MemberHolder for thread-safe data member holders

  FinalHandle for thread-safe "const" data member handles

  FinalView for thread-safe "const" data member views

  FinalHolder for thread-safe "const" data member holders

  WeakHandle for thread-safe weak data member handles

  WeakView for thread-safe weak data member views

  WeakHolder for thread-safe weak data member holders

Author:
  mf 2007.07.05

## Public Types
typedef spec::Handle | Handle
| Object Handle definition.
typedef spec::View | View
| Object View definition.
typedef spec::Holder | Holder
| Object Holder definition.
## Public Member Functions
virtual bool | equals (Object::View v) const
| Return true iff the specified Object is "equal" to this Object.
virtual size32_t | hashCode () const
| Return a hash code value for the Object.
virtual Object::Handle | clone () const
| Return a handle to a deep copy of the original Object.
virtual bool | isImmutable () const
| Return `true` iff no further changes can be made to the Object, that would effect the outcome of a call to its equals method.
virtual void | toStream (std::ostream &out) const
| Output a human-readable description of this Object to the given stream.
virtual size32_t | sizeOf () const
| Return an estimate as to the shallow byte size of the object.
void | wait () const
| Block the calling thread while waiting for notification.
void | wait (int64_t cMillis) const
| Block the calling thread while waiting for notification.
void | notify () const
| Notify a waiting thread.
void | notifyAll () const
| Notify all waiting threads.
bool | _isEscaped (bool fAttemptCapture=true) const
| Return if the Object is currently marked as escaped.
## Static Public Member Functions
static bool | equals (Object::View v1, Object::View v2)
| Compare two Objects for equality.
static void | toStream (std::ostream &out, Object::View v)
| Output an Object to a stream.
static Object::Handle | clone (Object::View v)
| Return a clone of the supplied Object.
static size32_t | hashCode (Object::View v)
| Return the hashCode for the specified object or 0 if the object is NULL.
## Protected Member Functions
| Object ()
| Construct a new Object.
| Object (const Object &that)
| Copy constructor.
virtual void | onInit ()
| Event called once the Object has finished being constructed.
virtual void | onConst ()
| Event called when the Object becomes only referenced via const pointers (Views).
virtual void | onEscape (bool fEscaped) const
| Event called when the guarding Object's escape state changes.
Object & | self ()
| Return a reference to the constructed base Object.
const Object & | self () const
| Return a reference to the constructed base Object.

## Member Function Documentation

virtual bool equals | ( | Object::View | v | ) | const `[virtual]`

Return true iff the specified Object is "equal" to this Object.

This method implements an equivalence relation on Objects:

- It is reflexive: for any non-null handle `h`, `h->equals(h)` must return `true`.
- It is symmetric: for any non-null handles `h1` and `h2`, `h1->equals(h2)` should return `true` if and only if `h2->equals(h1)` returns `true`.
- It is transitive: for any non-null handles `h1`, `h2`, and `h3`, if `h1->equals(h2)` returns `true` and `h2->equals(h3)` returns `true`, then `h1->equals(h3)` should return `true`.
- It is consistent: for any non-null handles `h1` and `h2`, multiple invocations of `h1->equals(h2)` consistently return `true` or consistently return `false`, provided no information used in comparisons on the objects is modified.
- If the supplied handle is `NULL` then `false` must be returned.

The default implementation is a reference equality comparison.

Parameters:

  | v | the Object::View to compare against, may be `NULL`

Returns:
  `true` iff the given handle references an Object that is "equal" to this Object

See also:
  equals(Object::View v1, Object::View v2)

Reimplemented in Array, Class, Float32, Float64, Managed, Primitive, String, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< char16_t >, Primitive< float32_t >, Primitive< int32_t >, Primitive< octet_t >, and Primitive< bool >.

virtual size32_t hashCode | ( |  | ) | const `[virtual]`

Return a hash code value for the Object.

This method is supported for the benefit of hash-based containers.

The general contract of `hashCode` is:

- Whenever it is invoked on the same Object more than once during an execution of an application, the `hashCode` method must consistently return the same value, provided no information used in `equals` comparisons on the object is modified. This value need not remain consistent from one execution of an application to another execution of the same application.
- If two Objects are equal according to the `equals` method, then calling the `hashCode` method on each of the two Objects must produce the same value.
- It is not required that if two Objects are unequal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce distinct results. However, the programmer should be aware that producing distinct results for unequal objects may improve the performance of hash-based containers.

The default implementation is identity based.

Returns:
  a hash code value for this Object

Reimplemented in RawDate, RawDateTime, RawDayTimeInterval, RawTime, RawTimeInterval, RawYearMonthInterval, SimplePofPath, Array, Class, Float32, Float64, Managed, Primitive, String, InetAddress, GenericSubject, GenericPrincipal, AbstractList, AbstractMap, AbstractSet, AbstractAggregator, CompositeAggregator, GroupAggregator, Binary, SafeComparator, CompositeKey, ConverterCollections::ConverterCollection, ConverterCollections::ConverterSet, ConverterCollections::ConverterMap, ConverterCollections::ConverterEntry, ConverterCollections::ConverterMapListener, AbstractCompositeExtractor, ConditionalExtractor, IdentityExtractor, KeyExtractor, PofExtractor, PofUpdater, ReflectionExtractor, ReflectionUpdater, TypedExtractor, TypedUpdater, AlwaysFilter, ArrayFilter, ComparisonFilter, FilterTrigger, KeyAssociatedFilter, MapEventFilter, MapEventTransformerFilter, NeverFilter, NotFilter, PresentFilter, ValueChangeEventFilter, MapListenerSupport::WrapperSynchronousListener, CompositeProcessor, ConditionalProcessor, ConditionalPut, ConditionalPutAll, ConditionalRemove, ExtractorProcessor, PreloadRequest, PropertyManipulator, PropertyProcessor, UpdaterProcessor, VersionedPut, VersionedPutAll, ReadOnlyMultiList::ListView, ReadOnlyMultiList::SetView, SafeHashMap::Entry, SafeHashMap::EntrySet, SimpleMapIndex, ExtractorEventTransformer, SemiLiteEventTransformer, UUID, WrapperCollections::AbstractWrapperIterator, WrapperCollections::AbstractWrapperCollection, WrapperCollections::AbstractWrapperSet, WrapperCollections::AbstractWrapperList, WrapperCollections::AbstractWrapperMap, WrapperCollections::AbstractWrapperEntry, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< char16_t >, Primitive< float32_t >, Primitive< int32_t >, Primitive< octet_t >, Primitive< bool >, TypedExtractor< RH::ValueType::BoxedType, C, M, coherence::lang::BoxHandle< RH::ValueType >, OH >, and TypedUpdater< AH::ValueType::BoxedType, C, M, coherence::lang::BoxHandle< AH::ValueType >, OH >.

virtual Object::Handle clone | ( |  | ) | const `[virtual]`

Return a handle to a deep copy of the original Object.

The returned clone should be sufficient decoupled from the original such that further modifications to the original Object will not be visible within the cloned object. More specifically, the following is expected to hold true.

     h->clone() != h &&
     h->clone()->equals(h) &&
     typeid(*h) == typeid(*(h->clone()))

Note that this suggests that data members of a cloned object are expected to cloned if they are tested for equality (via a call to equals) within the cloned object's equals method. If a data member is compared via reference equality, or not even considered within equals, then it does not necessarily need to be deeply cloned.

Object is cloneable, but it's derived classes are not automatically cloneable, and CloneNotSupportedExceptions are thrown. To be made cloneable the derived class should use the cloneable_spec<> helper template in its declaration, and define a protected copy constructor. The derived class does not need to override this method, as that is done by the cloneable_spec<> template.

Returns:
  a copy of the original Object

Exceptions:

  | CloneNotSupportedException | if the object cannot be deep cloned

See also:
  isImmutable()

Reimplemented in Array, Array< int32_t >, Array< octet_t >, Array< char >, and Array< bool >.

virtual bool isImmutable | ( |  | ) | const `[virtual]`

Return `true` iff no further changes can be made to the Object, that would effect the outcome of a call to its equals method.

Except for Objects which are naturally immutable (such as String), being immutable generally implies that the Object is only referenced via const pointers or views. Objects which hold references to child Objects, may need to take the immutability of their children into account when determining their own immutability.

This extended check is not performed by the default implementation, but can be integrated into the immutability checks by overriding this method, as well as making use of MemberHandles to reference child Objects.

A typical derived implementation may look as follows:

     bool isImmutable() const
         {
         if (m_fImmutable) // check recorded state
             {
             return true; // already marked as immutable, avoid calculation
             }
         else if (Object::isImmutable()) // ensure shallow immutability
             {
             // ensure deep immutability
             if (m_child1->isImmutable() && m_child2->isImmutable() ...
                                         && m_childN->isImmutable())
                 {
                 // record and return immutability
                 return m_fImmutable = true;
                 }
             // some Objects which comprise this Object are still mutable
             }
         return false;
         }

The default implementation return true iff the Object is only referenced via const pointers and or views.

Returns:
  true iff the Object is immutable

Reimplemented in RawDate, RawDateTime, RawDayTimeInterval, RawTime, RawTimeInterval, RawYearMonthInterval, Array, Primitive, String, GenericSubject, GenericPrincipal, AbstractList, Binary, TypedCollections::TypedMap::EntryConverter, WrapperCollections::AbstractWrapperCollection, WrapperCollections::AbstractWrapperSet, WrapperCollections::AbstractWrapperList, WrapperCollections::AbstractWrapperMap, WrapperCollections::AbstractWrapperEntry, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< char16_t >, Primitive< float32_t >, Primitive< int32_t >, Primitive< octet_t >, and Primitive< bool >.

virtual void toStream | ( | std::ostream & | out | ) | const `[virtual]`

Output a human-readable description of this Object to the given stream.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.

     Object::View vKey   = ...
     Object::View vValue = ...
     std::cout << vKey << " = " << vValue << std::endl;

     String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);

Parameters:

  | out | the stream used to output the description

Reimplemented in OctetArrayReadBuffer, RawDate, RawDateTime, RawDayTimeInterval, RawTime, RawTimeInterval, RawYearMonthInterval, SimplePofPath, SimplePofContext, AbstractHeapAnalyzer, Array, ClassBasedHeapAnalyzer::ClassStats, ClassBasedHeapAnalyzer::Snapshot, Exception, Managed, ObjectCountHeapAnalyzer::Snapshot, ObjectCountHeapAnalyzer, Primitive, StackTraceElement, String, SystemClassLoader, Thread, ThreadGroup, ThreadLocalReference, TypedBarrenClass, TypedClass, TypedExecutableClass, SimpleCacheStatistics, ConfigurableAddressProvider, InetAddress, InetSocketAddress, MemberEvent, GenericSubject, GenericPrincipal, AbstractCollection, AbstractLongArray, AbstractMap, AbstractSparseArray::Node, AbstractAggregator, CompositeAggregator, GroupAggregator, PriorityAggregator, AtomicCounter, Binary, SafeComparator, CompositeKey, ConditionalIndex, ConverterCollections::ConverterCollection, ConverterCollections::ConverterSet, ConverterCollections::ConverterMap, ConverterCollections::ConverterEntry, Describable, Event, AbstractCompositeExtractor, CompositeUpdater, ConditionalExtractor, IdentityExtractor, KeyExtractor, PofExtractor, PofUpdater, ReflectionExtractor, ReflectionUpdater, TypedExtractor, TypedUpdater, AlwaysFilter, ArrayFilter, ComparisonFilter, ExtractorFilter, FilterTrigger, InKeySetFilter, KeyAssociatedFilter, KeyFilter, LimitFilter, MapEventFilter, MapEventTransformerFilter, NeverFilter, NotFilter, PresentFilter, PriorityFilter, ValueChangeEventFilter, Listeners, MapEvent, MapListenerSupport, PriorityProcessor, SafeHashMap::Entry, ServiceEvent, SimpleMapIndex, ThreadGate, ThreadGate::Counter, ExtractorEventTransformer, SemiLiteEventTransformer, TreeMap::Node, UUID, WrapperCollections::AbstractWrapperIterator, WrapperCollections::AbstractWrapperCollection, WrapperCollections::AbstractWrapperSet, WrapperCollections::AbstractWrapperList, WrapperCollections::AbstractWrapperMap, WrapperCollections::AbstractWrapperEntry, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< char16_t >, Primitive< float32_t >, Primitive< int32_t >, Primitive< octet_t >, Primitive< bool >, TypedExtractor< RH::ValueType::BoxedType, C, M, coherence::lang::BoxHandle< RH::ValueType >, OH >, and TypedUpdater< AH::ValueType::BoxedType, C, M, coherence::lang::BoxHandle< AH::ValueType >, OH >.

virtual size32_t sizeOf | ( |  | ) | const `[virtual]`

Return an estimate as to the shallow byte size of the object.

The shallow size should not include the cost of referenced managed objects, or non-fixed dynamically allocated memory. That for a given object it is assumed that a call to this method will always return the same value.

For classes defined via the class_spec template an auto-generated implementation is provided which utilizes the standard C sizeof() operator to compute the size. User defined implementations are only needed to account for dynamic memory allocated during construction.

Returns:
  the approximate shallow byte size of the object

Reimplemented in Array, String, Array< int32_t >, Array< octet_t >, Array< char >, and Array< bool >.

void wait | ( |  | ) | const

Block the calling thread while waiting for notification.

The caller must be synchronized on the Object's monitor when calling this method. The monitor will be automatically released while the thread awaits notification, and re-acquired before the call returns. This method is subject to spurious wakeups, and the caller should externally verify that the condition being waited for has been reached.

To synchronize on an object, the COH_SYNCHRONIZED macro is used. The macro defines a block of code which is a critical section, during which no other thread may acquire synchronization on the same object.

     Object::Handle hObject = ...
     COH_SYNCHRONIZED (hObject)
       {
       while (testSomeCondition() == false)
         {
         hObject->wait();
         }
       }

See also:
  notify

  notifyAll

void wait | ( | int64_t | cMillis | ) | const

Block the calling thread while waiting for notification.

The caller must be synchronized on the Object's monitor when calling this method. The monitor will be automatically released while the thread awaits notification, and re-acquired before the call returns. This method is subject to spurious wakeups, and the caller should externally verify that the condition being waited for has been reached.

Parameters:

  | cMillis | the duration to wait to wait, a value of zero will wait indefinitely for notification

See also:
  wait

  notify

  notifyAll

void notify | ( |  | ) | const

Notify a waiting thread.

The caller must be synchronized on the Object's monitor when calling this method.

     Object::Handle hObject = ...
     COH_SYNCHRONIZED (hObject)
       {
       setSomeCondition(true);
       hObject->notify();
       }

See also:
  wait

  notifyAll

void notifyAll | ( |  | ) | const

Notify all waiting threads.

The caller must be synchronized on the Object's monitor when calling this method.

See also:
  wait

  notify

bool _isEscaped | ( | bool | fAttemptCapture = `true` | ) | const `[inline]`

Return if the Object is currently marked as escaped.

An escaped object is one which is known to be reachable by multiple threads.

Parameters:

  | fAttemptCapture | true if capture should be attempted

Returns:
  true if the Object is currently marked as escaped

virtual void onInit | ( |  | ) | `[protected, virtual]`

Event called once the Object has finished being constructed.

Specifically when the first attachment is made. This provides a safe point at which Handles/Views to "this" can be created. It is not safe to create Handles/Views to an Object from within its constructor, thus any operations which rely upon this should be deferred until the onInit event is triggered.

As with all event methods any derived implementation should include a call to the super class's implementation. Specifically delegation to Object::onInit() must eventually occur or an IllegalStateException will result.

The default implementation calls the onInit() method of each of the Object's SmartMembers.

Reimplemented in PortableException, ContinuousQueryCache, AbstractSparseArray::Node, AbstractStableIterator, and TreeMap::Node.

virtual void onConst | ( |  | ) | `[protected, virtual]`

Event called when the Object becomes only referenced via const pointers (Views).

Assuming a const-correct class, once this method returns no further visible changes can be made to the object.

As with all event methods any derived implementation should include a call to the super class's implementation.

The default implementation calls the onConst() method of each of the Object's SmartMembers.

See also:
  isImmutable

Reimplemented in Array, Array< int32_t >, Array< octet_t >, Array< char >, and Array< bool >.

virtual void onEscape | ( | bool | fEscaped | ) | const `[protected, virtual]`

Event called when the guarding Object's escape state changes.

As with all event methods any derived implementation should include a call to the super class's implementation. Ultimately delegation must reach Object::onEscape() which will perform the actual act of preparing the object for multi/single-threaded access.

Throughout the call it is guaranteed that the object remains visible to only a single thread, and as such it is not allowable to perform an action from within this method which would attempt to escape this object.

Parameters:

  | fEscaped | true if the object is escaping, false if it is being captured

Reimplemented in Array, LinkedList, Array< int32_t >, Array< octet_t >, Array< char >, and Array< bool >.

Object& self | ( |  | ) | `[inline, protected]`

Return a reference to the constructed base Object.

This reference is suitable for use in derived class constructors as the Object class will have completed construction.

Returns:
  the Object reference

const Object& self | ( |  | ) | const `[inline, protected]`

Return a reference to the constructed base Object.

Returns:
  the const Object reference

static bool equals | ( | Object::View | v1,
|  | Object::View | v2 |
| ) |  |  | `[static]`

Compare two Objects for equality.

This method implements an equivalence relation for two potentially `NULL` handles.

Parameters:

  | v1 | the first Object to compare
  | v2 | the second Object to compare

Returns:
  `true` iff v1 and v2 are `NULL` or reference Objects which are equal

static void toStream | ( | std::ostream & | out,
|  | Object::View | v |
| ) |  |  | `[static]`

Output an Object to a stream.

If the handle is NULL then the string "NULL" will be written to the stream.

Parameters:

  | out | the stream used to output the Object
  | v | the Object to output

static Object::Handle clone | ( | Object::View | v | ) | `[static]`

Return a clone of the supplied Object.

Parameters:

  | v | the Object to clone

Returns:
  a clone of the Object, or NULL if NULL was supplied

static size32_t hashCode | ( | Object::View | v | ) | `[inline, static]`

Return the hashCode for the specified object or 0 if the object is NULL.

Parameters:

  | v | the Object to hash

Returns:
  the object's hash.

The documentation for this class was generated from the following file:

- coherence/lang/Object.hpp

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.