This chapter describes changes, enhancements, and corrections made to the existing Oracle Coherence library (Getting Started, Developer's Guide, and User's Guide). The current Oracle Coherence documentation library can be found at the following URL:
https://download.oracle.com/docs/cd/E13924_01/index.htm
This section describes the changes made to the Overview for Implementors chapter in Getting Started with Oracle Coherence.
Table 2-1 illustrates the code changes made to Examples 8-1 and 8-2 in the Querying the Cache section. The changes are illustrated in italic and codeItalic.
Table 2-1 Changes Made to the Querying the Cache Section
In the Coherence Features by Edition appendix of Getting Started with Oracle Coherence, a change has been made to the text of Note 6.
Table 2-2 Changes Made to the Coherence Features by Edition Appendix
This section describes the changes made to the Understanding the Coherence C++ Object Model chapter in the Users Guide for Oracle Coherence. Corrected text appears in italics.
Table 2-3 illustrates the changes made to the Thread Safety section
Table 2-3 Text Changes Made to the Thread Safety Section
| Old Text | New Text |
|---|---|
|
Although the object model includes a thread-safe reference count, this does not provide automatic thread safety for the state of derived classes. As is typical it is up to each individual class implementation to choose to provide for higher level thread-safety. Regardless of the presence or lack of higher level thread-safety, the reference count remains thread-safe. |
Although the base Object class is thread-safe, this cannot provide automatic thread safety for the state of derived classes. As is typical it is up to each individual derived class implementation to provide for higher level thread-safety. The object model provides several facilities to aid in writing thread-safe code. |
Table 2-4 illustrates the changes made to the Thread Safe Handles section.
Table 2-4 Changes Made to the Thread Safe Handles Section
| Old Text | New Text |
|---|---|
|
The Handle, View, and Holder nested types defined on managed classes are not thread-safe. That is it is not safe to have multiple threads use the same handle if any of them may change the handle to reference another object. There is an important distinction here, we are discussing the thread-safety of the handle, not the object referenced by the handle. Note it is safe to have multiple distinct handles reference the same object from different threads without additional synchronization. |
The Handle, View, and Holder nested types defined on managed classes are intentionally not thread-safe. That is it is not safe to have multiple threads share a single handle. There is an important distinction here, we are discussing the thread-safety of the handle, not the object referenced by the handle. It is safe to have multiple distinct handles reference the same object from different threads without additional synchronization. |
|
This lack of thread-safety for these handle types offers a significant performance optimization by assuming that the vast majority of handles are stack allocated. So long as references to these stack allocated handles are not shared across threads, there is no thread-safety issue to be concerned with. Typically precautions are needed when sharing a handle in one of the following conditions.
|
This lack of thread-safety for these handle types offers a significant performance optimization as the vast majority of handles are stack allocated. So long as references to these stack allocated handles are not shared across threads, there is no thread-safety issue to be concerned with. Thread-safe handles are needed any time a single handle may be referenced by multiple threads. Typical cases include:
|
|
There are optimizations in place for the first case, namely the special thread-safe handle types:
|
The use of standard handles should be replaced with thread-safe handles in such cases. The object model includes the following set of thread-safe handles.
|
|
These handle types may be read and written from multiple thread without the need for additional synchronization. They are primarily intended for use as the data-members of other managed classes, and they make use of their parent's internal atomic state to provide thread-safety. When using these handle types it is recommended that they be read into a normal stack based handle if they will be accessed more than once within a code block. This assignment to a normal stack based handle is thread-safe, and when completed allows for essentially free dereferencing of the stack based handle. Note that when initializing thread-safe handles a reference to a guardian Object must be supplied as the first parameter, this reference can be obtained by calling |
These handle types may be read and written from multiple thread without the need for additional synchronization. They are primarily intended for use as the data-members of other managed classes, each instance is provided with a reference to a guardian managed Object. The guardian's internal thread-safe atomic state is used to provide thread-safety to the handle. When using these handle types it is recommended that they be read into a normal stack based handle if they will be accessed more than once within a code block. This assignment to a standard stack based handle is thread-safe, and when completed allows for essentially free dereferencing of the stack based handle. Note that when initializing thread-safe handles a reference to a guardian Object must be supplied as the first parameter, this reference can be obtained by calling |
|
The same basic technique can be applied to non-managed classes as well. Since non-managed classes do not extend |
The same basic technique can be applied to non-managed classes as well. Since non-managed classes do not extend Note that when writing managed classes it is preferable to obtain a guardian through a call to |
|
NA |
Add the following note before Example 2-18: Note: In the rare case that one of these handles is declared by using the |
Table 2-5 illustrates the changes made to the Memory Leak Detection section:
Table 2-5 Changes Made to the Memory Leak Detection Section
| Old Text | New Text |
|---|---|
|
|
This section describes the changes made to the Building Integration Objects for C++ Clients chapter in the User's Guide for Oracle Coherence.
Table 2-6 illustrates the changes made to the chapter overview. Corrected text appears in italics.
Table 2-6 Changes Made to the Building Integration Objects for C++ Clients Overview
| Old Text | New Text |
|---|---|
|
Enabling C++ clients to successfully store C++ based objects within a Coherence cluster relies on a platform-independent serialization format known as POF (Portable Object Format). POF allows value objects to be encoded into a binary stream in such a way that the platform and language origin of the object is irrelevant. |
Enabling C+\+ clients to successfully store C+\+ based objects within a Coherence cluster relies on a platform-independent serialization format known as POF (Portable Object Format). POF allows value objects to be encoded into a binary stream in such a way that the platform and language origin of the object is irrelevant. The stream can then be deserialized in an alternate language using a similar POF-based class definition. |
A new section, POF Intrinsics, has been added to the Building Integration Objects for C++ Clients chapter.
The following types are internally supported by POF, and do not require special handling by the user:
String
Integer16, Integer64
Float32, Float64
Array<> of primitives
ObjectArray
Boolean
Octet
Character16
Additionally, automatic POF serialization is provided for classes implementing these common interfaces:
Map
Collection
Exception
Corrections were made to Example 3-6 in the PofSerializer (External Serialization) section. The corrected code appears in bold italic.
#include "coherence/lang.ns"
using namespace coherence::lang;
class Address
: public cloneable_spec<Address> // extends<Object> is implied
{
friend class factory<Address>;
protected: // constructors
Address(String::View vsCity, String::View vsState, int32_t nZip)
: m_vsCity(self(), vsCity), m_vsState(self(), vsState), m_nZip(nZip) {}
Address(const Address& that)
: super(that), m_vsCity(self(), that.m_vsCity), m_sState(self(), that.m_vsState), m_nZip(that.m_nZip) {}
public: // Address interface
virtual String::View getCity() const {return m_vsCity;}
virtual String::View getState() const {return m_vsState;}
virtual int32_t getZip() const {return m_nZip;}
public: // Object interface
virtual bool equals(Object::View that) const
{
if (instanceof<Address::View>(that))
{
Address::View vThat = cast<Address::View>(that);
return getZip() == vThat->getZip() &&
Object::equals(getState(), vThat->getState()) &&
Object::equals(getCity(), vThat->getCity());
}
return false;
}
virtual size32_t hashCode() const
{
return (size32_t) m_nZip;
}
virtual void toStream(std::ostream& out) const
{
out << getCity() << ", " << getState() << " " << getZip();
}
private:
const MemberView<String> m_vsCity;
const MemberView<String> m_vsState;
const int32_t m_nZip;
};
Table 2-7 illustrates the changes made to the Need for Java Classes section. Corrected text appears in italic.
Table 2-7 Changes Made to the Need for Java Classes Section
| Old Text | New Text |
|---|---|
|
After completing any of the above approaches your data object will be ready to be stored within the Coherence cluster. This will allow you to perform |
After completing any of the above approaches your data object will be ready to be stored within the Coherence cluster. This alone will allow you to perform |
This section describes the changes made to the How to Manage Coherence Using JMX chapter of the Developer's Guide for Oracle Coherence.
Table 2-8 illustrates the changes made to the Configuring the Coherence Management Framework section. Changed text is in italic.
Table 2-8 Changes Made to the Configuring the Coherence Management Framework Section
| Old Text | New Text |
|---|---|
|
The use of dedicated JMX cluster members is a common pattern. This approach avoids loading JMX software into every single cluster member, while still providing fault-tolerance should a single JMX member run into issues. |
The use of dedicated JMX cluster members is a common pattern. This approach avoids loading JMX software into every single cluster member, while still providing fault-tolerance should a single JMX member run into issues. Setting |
This section describes the changes made to the Production Checklist appendix of the Developer's Guide for Oracle Coherence.
Table 2-9 illustrates changes made to the JVM section. New text is in italic.
Table 2-9 Changes Made to the JVM Section
| Old Text | New Text |
|---|---|
|
Oracle recommends testing and deploying using the latest supported Sun JVM based on your platform and Coherence version. |
Oracle recommends testing and deploying using the latest supported Sun JVM based on your platform and Coherence version. It has been observed that running Coherence on 1.5 and later JVMs exhibits significant performance improvements as compared to running on older JVMs. |
Table 2-10 illustrates the changes made to the Coherence Cache Configuration section. Corrected text is in italic.
Table 2-10 Changes Made to the Coherence Cache Configuration Section
| Old Text | New Text |
|---|---|
|
Unless explicitly specified all cluster nodes will be storage enabled, i.e. will act as cache servers. It is important to control which nodes in your production environment will be storage enabled and storage disabled. The |
Unless explicitly specified all cluster nodes will be storage enabled, i.e. will act as cache servers. It is important to control which nodes in your production environment will be storage enabled and storage disabled. The |