Oracle® Fusion Middleware C++ API Reference for Oracle Coherence
12c (12.2.1.3.0)
E80355-01

coherence::lang::Object

Object Class Reference

#include <coherence/lang/Object.hpp>

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 &) const
	Deprecated as of 12.2.1.
virtual TypedHandle < const String >	toString () const
	Output a human-readable description of this Object to the given stream.
virtual size64_t	sizeOf (bool fDeep=false) const
	Return an estimate as to the 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 TypedHandle < const String >	toString (Object::View v)
	Return the string form of the supplied Object.
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, Method, Primitive, Array< int64_t >, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< float32_t >, Primitive< size64_t >, Primitive< int32_t >, Primitive< size32_t >, Primitive< octet_t >, Primitive< bool >, and Primitive< wchar16_t >.

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, Method, Primitive, InetAddress, GenericSubject, GenericPrincipal, AbstractList, AbstractLongArray, 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, CacheEventFilter, ComparisonFilter, FilterTrigger, KeyAssociatedFilter, MapEventFilter, MapEventTransformerFilter, NeverFilter, NotFilter, PresentFilter, ValueChangeEventFilter, MapListenerSupport::WrapperSynchronousListener, Optional, CompositeProcessor, ConditionalProcessor, ConditionalPut, ConditionalPutAll, ConditionalRemove, ExtractorProcessor, PreloadRequest, PropertyManipulator, PropertyProcessor, UpdaterProcessor, VersionedPut, VersionedPutAll, ReadOnlyMultiList::ListView, ReadOnlyMultiList::SetView, SafeHashMap::Entry, SafeHashMap::EntrySet, SimpleMapIndex, SimpleQueryRecord::PartialResult::IndexLookupRecord, ExtractorEventTransformer, SemiLiteEventTransformer, UUID, WrapperCollections::AbstractWrapperIterator, WrapperCollections::AbstractWrapperCollection, WrapperCollections::AbstractWrapperSet, WrapperCollections::AbstractWrapperList, WrapperCollections::AbstractWrapperMap, WrapperCollections::AbstractWrapperEntry, Array< int64_t >, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< float32_t >, Primitive< size64_t >, Primitive< int32_t >, Primitive< size32_t >, Primitive< octet_t >, Primitive< bool >, Primitive< wchar16_t >, 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< int64_t >, 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, GenericSubject, GenericPrincipal, AbstractList, Binary, TypedCollections::TypedMap::EntryConverter, WrapperCollections::AbstractWrapperCollection, WrapperCollections::AbstractWrapperSet, WrapperCollections::AbstractWrapperList, WrapperCollections::AbstractWrapperMap, WrapperCollections::AbstractWrapperEntry, Array< int64_t >, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< float32_t >, Primitive< size64_t >, Primitive< int32_t >, Primitive< size32_t >, Primitive< octet_t >, Primitive< bool >, and Primitive< wchar16_t >.

virtual void toStream ( std::ostream & ) const [inline, virtual]

Deprecated as of 12.2.1.

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

As of 12.2.1 this method is deprecated in favor of Object::toString() which includes support for unicode output and is agnostic to differences between ostream library versions.

The default implementation of toStream will simply delegate to toString.

Deprecated:: 12.2.1

virtual TypedHandle<const String> toString ( ) const [virtual]

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

Note that when overriding this method the return type must be TypedHandle<const String> rather then String::View. These two types are assignment compatible but not equivalent and declaring the override with String::View will not be a compatible override.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toString 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 and is generally how toString() will be implemented.

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

 String::View vs = COH_TO_STRING(vKey << " = " << vValue);

The COH_TO_STRING macro is also the most common way to implement the toString method. For example:

 virtual TypedHandle<const String> Person::toString() const
     {
     return COH_TO_STRING("Name: " << f_sName << " SSN: " << f_nSSN);
     }

Returns:: a string representation of this object

Reimplemented in ConfigurableSerializerFactory, OctetArrayReadBuffer, RawDate, RawDateTime, RawDayTimeInterval, RawTime, RawTimeInterval, RawYearMonthInterval, SimplePofPath, SimplePofContext, AbstractHeapAnalyzer, Array, ClassBasedHeapAnalyzer::ClassStats, ClassBasedHeapAnalyzer::Snapshot, Exception, Managed, Method, ObjectCountHeapAnalyzer::Snapshot, ObjectCountHeapAnalyzer, Primitive, StackTraceElement, SystemClassLoader, Thread, ThreadGroup, ThreadLocalReference, TypedBarrenClass, TypedClass, TypedExecutableClass, AbstractBundler, AbstractBundler::Bundle, AbstractBundler::Statistics, CachingMap, OldCache, SimpleCacheStatistics, WrapperNamedCache, ConfigurableAddressProvider, ConfigurableAddressProviderFactory, InetAddress, InetSocketAddress, MemberEvent, PartitionSet, SingleAddressProvider, 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, BetweenFilter, ComparisonFilter, ExtractorFilter, FilterTrigger, InKeySetFilter, KeyAssociatedFilter, KeyFilter, LimitFilter, MapEventFilter, MapEventTransformerFilter, NeverFilter, NotFilter, PresentFilter, PriorityFilter, ValueChangeEventFilter, Listeners, MapEvent, MapListenerSupport, Optional, PriorityProcessor, SafeHashMap::Entry, ServiceEvent, SimpleMapIndex, SimpleQueryRecord, ThreadGate, ThreadGate::Counter, ExtractorEventTransformer, SemiLiteEventTransformer, TreeMap::Node, UUID, WrapperCollections::AbstractWrapperIterator, WrapperCollections::AbstractWrapperCollection, WrapperCollections::AbstractWrapperSet, WrapperCollections::AbstractWrapperList, WrapperCollections::AbstractWrapperMap, WrapperCollections::AbstractWrapperEntry, Array< int64_t >, Array< int32_t >, Array< octet_t >, Array< char >, Array< bool >, Primitive< int64_t >, Primitive< int16_t >, Primitive< float64_t >, Primitive< float32_t >, Primitive< size64_t >, Primitive< int32_t >, Primitive< size32_t >, Primitive< octet_t >, Primitive< bool >, Primitive< wchar16_t >, 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 size64_t sizeOf ( bool fDeep = false ) const [virtual]

Return an estimate as to the 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 when the shallow size is requested.

The deep size should be the shallow size plus the size of any referenced objects. Unlike the shallow size the deep size may change over time. The default implementation provided by Object will traverse the object graph of all managed objects which it references and include their sizes in the computed deep size. In general it is sufficient to simply delegate to super::sizeOf(true) for deep calculations.

For classes implemented via class_spec, a variant of this method will be automatically produced which will utilize sizeof(*this) to compute the shallow size, and super::sizeOf(true) to compute the deep size. As such it is generally not necessary to provide custom implmenetations of this method.

Parameters:

fDeep

true if the size should include the size of referenced objects

Returns:: the approximate shallow byte size of the object

Reimplemented in Array, LinkedList::ListElement, Array< int64_t >, 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.

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 CachingMap, ContinuousQueryCache, NearCache, 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< int64_t >, 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 OctetArrayWriteBuffer, Array, LinkedList, Array< int64_t >, 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 TypedHandle<const String> toString ( Object::View v ) [static]

Return the string form of the supplied Object.

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

Parameters:

the Object to output

Returns:: the object's toString

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

Return a clone of the supplied Object.

Parameters:

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:

the Object to hash

Returns:: the object's hash.

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

coherence/lang/Object.hpp

Object Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Function Documentation