JNIpp 1.0
JNI meets C++
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions
java::Object Class Reference

The Object class, root of all. More...

Inheritance diagram for java::Object:
jni::AbstractObject java::CharSequence java::Class java::ObjectArray< ObjectType > java::PrimitiveArray< JType > java::Throwable java::String java::Exception java::RuntimeException

List of all members.

Public Member Functions

 Object ()
 Creates java.lang.Object and wraps it.
 Object (const jni::LObject &object)
 Wraps object.
bool IsLive () const
 Tests whether this object is live.
void Retain () const
 Increments reference counter.
void Release () const
 Decrements reference counter.
virtual jobject GetJObject () const
 Returns contained Java object.
bool Equals (PObject other) const
 Indicates whether some other object is "equal to" this one.
PClass GetClass () const
 Returns object's class.
jint GetHashCode () const
 Returns a hash code value for the object.
void Notify ()
 Wakes up a single thread that is waiting on this object's monitor.
void NotifyAll ()
 Wakes up all threads that are waiting on this object's monitor.
void Wait ()
 Causes current thread to wait until another thread invokes the Notify() method or the NotifyAll() method for this object.
void Wait (jlong timeout)
 Causes current thread to wait until either another thread invokes the Notify() method or the NotifyAll() method for this object, or a specified amount of time has elapsed.
void Wait (jlong timeout, jint nanos)
 Causes current thread to wait until either another thread invokes the Notify() method or the NotifyAll() method for this object, or a specified amount of time has elapsed.
PString ToString () const
 Returns a string representation of the object.

Static Public Member Functions

static java::PClass GetTypeClass ()
 Returns Java class for this class.
static jfieldID GetInstanceFieldID ()
 Returns instance field id.
static Object * GetLiveInstance (jobject object, jfieldID instanceFieldID)
 Retrieves object instance pointer from the Java object.
static PClass GetClass (const AbstractObject &object)
 Returns class of the specified object.

Static Public Attributes

static const bool IsLiveType
 Flag indicating whether class is live.

Protected Member Functions

 Object (const jni::LObject &object, jfieldID instanceFieldID)
 Constructs live object.
virtual ~Object ()
 Destroys reference to the contained Java object.

Detailed Description

The Object class, root of all.

Wrapper for java.lang.Object.

Object class uses intrusive reference counting: Retain() adds a reference, Release() releases it. However, you should use ObjectPointer for managing objects lifetime in an exception safe manner.

When subclassing Object you need to decide whether to implement wrapper or live class:

  • Wrapper classes let you to manipulate existing Java classes.
  • Live classes let you to implement Java class methods in native code. Live classes can also call methods and get/set fields.

More about creating a wrapper class:

  • Wrapper class can only be derived from other wrapper class (like Object or Exception).
  • JB_WRAPPER_CLASS() is used to declare wrapper class and JB_DEFINE_WRAPPER_CLASS() is used to describe methods and fields that wrapper class is going to access.
  • Wrapping constructor Object(const jni::LObject&) is used to construct instances of a wrapper class.
  • In most cases wrapper class should also implement protected live constructor Object(const jni::LObject&,jfieldID) to allow live classes to be derived.
  • Wrapper class object is destroyed when last reference is released by Release() method.
  • Wrapper class objects are stateless, they are created ad-hoc and discarded after the use.
  • EmailValidator example shows how to create wrapper classes.

More about creating a live class:

  • Java class should define the following two members to be manageable by a live class:
    • protected native void finalize();
    • private int nativeInstance;
  • Live class can only be derived from wrapper class that have live constructor available (e.g. Object or Exception but not String). Live class can't be derived from other live class.
  • JB_LIVE_CLASS() is used to declare live class and JB_DEFINE_LIVE_CLASS() is used to describe methods, fields and callbacks. Callbacks are class methods that implement Java class methods declared native. Association between callbacks and corresponding Java methods is established in JB_DEFINE_LIVE_CLASS().
  • Live constructor Object(const jni::LObject&,jfieldID) is used to construct instances of a live class.
  • Live class object is destroyed only when the Java object (which was supplied to the live constructor) is collected by GC.
  • LiveThread example shows how to override method of an existing Java class (Thread) and NativeSound example shows how to implement Java class completely in native code.
Examples:

EmailValidator.cpp, LiveThread.cpp, and NativeSound.cpp.

Constructor & Destructor Documentation

java::Object::Object ( )

Creates java.lang.Object and wraps it.

See Object(const jni::LObject&) for details.

java::Object::Object ( const jni::LObject &  object)

Wraps object.

Method performs the following:

  • Sets reference count to 0.
  • Stores Java object and adds global reference to it.

See also Object(const jni::LObject&,jfieldID).

java::Object::Object ( const jni::LObject &  object,
jfieldID  instanceFieldID 
) [protected]

Constructs live object.

Method performs the following:

  • Sets instance pointer (this) to the int field identified by instanceFieldID.
  • Sets reference count to 1.
  • Stores Java object and adds weak reference to it.

See also Object(const jni::LObject&).

Member Function Documentation

static jfieldID java::Object::GetInstanceFieldID ( ) [static]

Returns instance field id.

Instance field must be declared as:

static java::PClass java::Object::GetTypeClass ( ) [static]

Returns Java class for this class.

Added by JB_WRAPPER_CLASS() / JB_LIVE_CLASS().

void java::Object::Release ( ) const

Decrements reference counter.

For live objects decrementing counter from 2 to 1 switches contained Java object from global to weak reference allowing Java's GC to collect it.

When reference count hits zero (or goes below) object is deleted.

void java::Object::Retain ( ) const

Increments reference counter.

If this object is live incrementing counter from 1 to 2 switches contained Java object from weak to global reference.

Member Data Documentation

const bool java::Object::IsLiveType [static]

Flag indicating whether class is live.

Added by JB_WRAPPER_CLASS() / JB_LIVE_CLASS().