coherence34 tuturial

5/24/2018 Coherence34 Tuturial

1/178

Oracle Coherence

Tutorial for Oracle Coherence

Release 3.4.1

E14135-01

January 2009


2/178

Oracle Coherence Tutorial for Oracle Coherence, Release 3.4.1

E14135-01

Copyright 2009, Oracle and/or its affiliates. All rights reserved.

Primary Author: Thomas Pfaeffle

Contributing Author: Noah Arliss, Jason Howes, Mark Falco, Alex Gleyzer, Gene Gleyzer, Adam Leftik,David Leibs, Andy Nguyen, Brian Oliver, Patrick Peralta, Cameron Purdy, Jonathan Purdy, Everet Williams,

Tom Beerbower, John Speidel

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverseengineering, disassembly, or decompilation of this software, unless required by law for interoperability, isprohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical datadelivered to U.S. Government customers are "commercial computer software" or "commercial technical data"pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As

such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions andlicense terms set forth in the applicable Government contract, and, to the extent applicable by the terms ofthe Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer SoftwareLicense (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is notdeveloped or intended for use in any inherently dangerous applications, including applications which maycreate a risk of personal injury. If you use this software in dangerous applications, then you shall beresponsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe useof this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use ofthis software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarksof their respective owners.

This software and documentation may provide access to or information on content, products, and servicesfrom third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim allwarranties of any kind with respect to third-party content, products, and services. Oracle Corporation andits affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use ofthird-party content, products, or services.


3/178

iii

Contents

Preface ................................................................................................................................................................. xi

Audience....................................................................................................................................................... xi

Documentation Accessibility..................................................................................................................... xi

Related Documents .................................................................................................................................... xii

Conventions ................................................................................................................................................ xii

1 Installing Coherence and JDeveloper

Downloading and Installing Coherence.............................................................................................. 1-1

Downloading and Installing JDeveloper ............................................................................................ 1-1

Testing a Coherence Installation ........................................................................................................... 1-2

Troubleshooting Cache Server Clustering .................................................................................. 1-11

Restricting Coherence to Your Own Host ............................................................................ 1-12

Advanced Steps to Restrict Coherence to Your Own Host ............................................... 1-13

2 Using JDeveloper with Coherence

Configuring Oracle JDeveloper for Coherence .................................................................................. 2-1Accessing the Data Grid from Java ....................................................................................................... 2-8

Creating Your First Coherence-Based Java Application ................................................................ 2-16

3 Leaving Strings Behind

Introduction............................................................................................................................................... 3-1

Creating and Caching Complex Objects.............................................................................................. 3-1

Caching a Complex Object using Java Serialization...................................................................... 3-20

Caching a Complex Object using Coherence PortableObject ...................................................... 3-24

4 Loading Data Into a Cache

Introduction............................................................................................................................................... 4-1

Populating a Cache with Domain Objects .......................................................................................... 4-2

Querying and Aggregating Data in the Cache ................................................................................... 4-8

5 Observing Data Changes

Introduction............................................................................................................................................... 5-1

Creating a Cache Listener and Responding to Changes ................................................................... 5-2

Creating a Chat Program ...................................................................................................................... 5-10


4/178

iv

Working with Partitions and Composite Keys ................................................................................ 5-15

6 In-Place Processing of Data

Introduction............................................................................................................................................... 6-1

Modifying and Processing Data Entries ............................................................................................. 6-2

7 Using JPA with Coherence

Introduction............................................................................................................................................... 7-1

Mapping Relational Data to Java Objects with JPA.......................................................................... 7-1

8 Interacting with the Cache and the Database

Introduction............................................................................................................................................... 8-1

Creating and Configuring a Coherence Cache with Oracle JDeveloper ....................................... 8-2

Index


5/178

v

List of Examples

11 cache-server.cmd File with an Edited COHERENCE_HOME ............................................ 1-312 Output from Starting a Coherence Cache Server................................................................... 1-413 coherence.cmd File with an Edited COHERENCE_HOME................................................. 1-614 Output from Starting the Coherence Cache Client................................................................ 1-715 Output from Starting a Coherence Cache ............................................................................... 1-916 Exercising Coherence Commands ........................................................................................ 1-10

17 Multicast-Listener Fragment of tangosol-coherence.xml File ........................................... 1-1221 Creating a NamedCache; Inserting and Verifying Values ............................................... 2-1222 Getting a Value from the Cache............................................................................................. 2-1323 Sample Coherence-Based Java Application......................................................................... 2-1731 Comparing an Object from the Cache with the Original ................................................... 3-1032 New Element in POF Configuration File....................................................... 3-1333 Serializer Section in the Cache Configuration File.............................................................. 3-1434 Section in the Cache Configuration File....................................................... 3-1435 Sample pof-cache-config.cmd File......................................................................................... 3-1536 Starting the POF Cache Server............................................................................................... 3-1637 Attributes for a Sample Serializable Class ........................................................................... 3-2038 Sample Domain Object for the Coherence Cache ............................................................... 3-20

39 Sample Console Application.................................................................................................. 3-22310 Sample PortableObject Implementation............................................................................... 3-25311 Output from Starting the Server with a POF Configuration ............................................. 3-2841 Sample Code to Open and Close a Text File ........................................................................... 4-142 Sample Code to Split a String.................................................................................................... 4-143 Sample Code to Parse a Date..................................................................................................... 4-244 Sample Cache Loading Program .............................................................................................. 4-245 Sample Stopwatch Program ...................................................................................................... 4-446 Sample PopulatePeople Class ................................................................................................ 4-1447 Sample QueryExample Class ................................................................................................. 4-1548 Methods to Aggregate Over Keys or by Specifying Filters ............................................... 4-1749 Sample Data Aggregation Class ............................................................................................ 4-1951 Listener Methods on a NamedCache....................................................................................... 5-1

52 Code Pattern for Registering an Event .................................................................................... 5-153 Sample Listener Class................................................................................................................. 5-254 Sample Program to Put a New Object in the Cache .............................................................. 5-455 Sample Code that Listens for an Update to an Object........................................................... 5-756 Sample Chat Program ............................................................................................................. 5-1057 Sample Chat Client Program.................................................................................................. 5-1258 Inner Class to Implement a Key Association for Data Affinity......................................... 5-1659 Sample Code to Create and Use an Inner Class within Coherence.................................. 5-16510 Implementation of the Person Object with a Key Inner Class........................................... 5-19511 Sample Code to Create an Object and Put and Get it From the Cache ............................ 5-23512 Code to Add Entries to KeyTester2....................................................................................... 5-24513 Sample Code for an Alternate KeyTester Class................................................................... 5-2561 Sample Employee Class ............................................................................................................. 6-4

62 Sample Raise Salary Class ......................................................................................................... 6-763 Sample Program to Test RaiseSalary Class ............................................................................ 6-764 Sample Program to Show Where Data is Held.................................................................... 6-1065 Sample Program to Trace Member Location of Employees .............................................. 6-1066 Output of WhereAreMyEmployees Class with One Cache Server Console................... 6-1167 Response on Cache Server Console 1.................................................................................... 6-1168 Response on Cache Server Console 2.................................................................................... 6-1171 persistance.xml File Contents................................................................................................. 7-1472 Cache Configuration for JPA.................................................................................................. 7-1573 Modified jpa-cache-server.cmd File ...................................................................................... 7-16


6/178

vi

74 Sample Employee Class File................................................................................................... 7-2081 Cache Configuration File ........................................................................................................... 8-682 Implementation of a Coherence Cache ................................................................................... 8-783 SQL Script for Creating a Database Table ............................................................................... 8-984 Database CacheStore Implementation.................................................................................. 8-1085 Database Cache Configuration File....................................................................................... 8-1386 Implementation for the Database Cache Class File ............................................................ 8-15


7/178

vii

List of Tables

11 Network Addresses and Ports Used by Coherence.............................................................. 1-221 Methods in the NamedCache Interface .................................................................................. 2-922 Methods in the CacheFactory Class ........................................................................................ 2-941 Throughput Calculations: Using PortableObject versus Serialization............................... 4-781 Descriptions of Cache Types .................................................................................................... 8-2

82 Types of Read-Write Caching Supported by Coherence .................................................. 8-15


8/178

viii

List of Figures

21 Select Role Dialog Box................................................................................................................ 2-222 Creating an Application in JDeveloper.................................................................................... 2-323 Default Properties Dialog Box................................................................................................... 2-424 Add Library Dialog Box............................................................................................................. 2-525 Create Library Dialog Box ......................................................................................................... 2-6

26 Select Path Entry Dialog Box..................................................................................................... 2-727 Create Library Dialog Box with the Coherence Jar on the Classpath ................................ 2-828 Choosing Projects in the New Gallery .................................................................................. 2-1029 Providing Project Details ........................................................................................................ 2-11210 Providing Java Class Details .................................................................................................. 2-11211 Output of Program to Create a NamedCache and to Store and Retrieve Values .......... 2-13212 Output from the Sample Reader Program ........................................................................... 2-14213 Output from the Sample Reader Program with a Running Cache Server ...................... 2-14214 Editing Run Configuration Properties.................................................................................. 2-15215 Output from JDeveloper if Storage is Disabled................................................................... 2-16216 Output from Coherence-Based Java ApplicationNo Value for the Key...................... 2-17217 Output from Coherence-Based Java ApplicationA Data Value for the Key ............... 2-1831 Creating a New Project in the New Gallery............................................................................ 3-2

32 Naming the New Project............................................................................................................ 3-333 Configuring Java Settings for the New Project....................................................................... 3-434 Creating the Java Class............................................................................................................... 3-535 Naming the Java Class ............................................................................................................... 3-536 Person Class in the JDeveloper Code Editor .......................................................................... 3-637 Generating Accessors for the Java Class Attributes............................................................... 3-738 Generating Constructors for the Java Class ............................................................................ 3-839 Generating equals() and hashCode() Methods....................................................................... 3-8310 Setting Java Runtime Options................................................................................................... 3-9311 Creating a Java Class with a main() Method ....................................................................... 3-10312 Results of Running PersonExample.java File ..................................................................... 3-11313 Implement Methods Dialog Box............................................................................................ 3-12314 Implementing the PortableObject.readExternal and writeExternal Methods ................ 3-13315 Adding Labs and Configuration Files to the Classpath..................................................... 3-18316 Setting the Runtime Profile..................................................................................................... 3-19317 PersonExample Output Run from JDeveloper.................................................................... 3-19318 Project Properties for the EndOfDayStockSummary Application.................................... 3-23319 Output from the CacheAnObject Console Application .................................................... 3-24320 Setting Java Options for the PortableObject Implementation ........................................... 3-27321 Running EndOfDayStockSummary with a PortableObject Implementation ................. 3-2841 Sample Program Run without a Cache Server ....................................................................... 4-542 Sample Program Run with One Cache Server........................................................................ 4-543 Sample Program Run with Two Cache Servers ..................................................................... 4-644 Sample Program Run with Two Cache Servers and Local Storage Set to False................ 4-645 Sample Program Run with Pof Serialization .......................................................................... 4-7

46 Creating a New Project ........................................................................................................... 4-1047 Setting Runtime Parameters................................................................................................... 4-1148 Adding Jars and Directories to Classpath ............................................................................ 4-1249 Adding Classes to the Classpath ........................................................................................... 4-13410 Creating a Java Class ............................................................................................................... 4-13411 Results of Populating the Cache ............................................................................................ 4-15412 Creating a Query Class ........................................................................................................... 4-15413 Results of Executing the Query.............................................................................................. 4-17414 Creating an Aggregation Class .............................................................................................. 4-18415 Creating the getAgeDouble Method..................................................................................... 4-18416 Aggregation Process Run with One Cache Server.............................................................. 4-20


9/178

ix

417 Aggregation Process Run with Two Cache Servers............................................................ 4-21418 Aggregation Process Run with Three Cache Servers ......................................................... 4-21419 Aggregation Process Run with One Cache Server and Indexing ..................................... 4-22420 Aggregation Process Run with Three Cache Servers and Indexing................................. 4-2251 Creating a Listener Class ........................................................................................................... 5-252 Listener Program Waiting for Events ...................................................................................... 5-453 Creating a PersonEventTester Class ........................................................................................ 5-4

54 Output from the ListenForNewPerson Class ......................................................................... 5-555 Output from the PersonEventTester Class.............................................................................. 5-656 New Record Detected by the ListenForNewPerson Class.................................................... 5-657 Creating an ListenForUpdatedPerson Class........................................................................... 5-758 Output of the ListenForNewPerson Class .............................................................................. 5-859 Output of the ListenForUpdatedPerson Class ....................................................................... 5-9510 Output from PersonEventTester Class .................................................................................... 5-9511 Output from the ListenForNewPerson Class ......................................................................... 5-9512 Output from the ListenForUpdatedPerson Class ............................................................... 5-10513 Creating a Chat Program ........................................................................................................ 5-10514 Creating a Chat Client Program ............................................................................................ 5-12515 Output of the Chat Program .................................................................................................. 5-15516 Creating a New Project ........................................................................................................... 5-17

517 Turning Off Local Storage and Setting Log Level for the Runtime Configuration........ 5-18518 Creating the Person Class ....................................................................................................... 5-18519 Creating a KeyTester Class..................................................................................................... 5-23520 Creating the KeyTester2 Class ............................................................................................... 5-2461 Creating a New Project .............................................................................................................. 6-262 Edit the Runtime Configuration ............................................................................................... 6-363 Creating the Employee Class .................................................................................................... 6-464 Create Raise Salary Class........................................................................................................... 6-665 Creating the Invoke Test Class.................................................................................................. 6-766 Class Not Found Error ............................................................................................................... 6-867 A Successful Run of the Invoke Test Class ............................................................................. 6-968 Creating the Say Hello Processor Class ................................................................................... 6-969 Creating the Where Are My Employees Class .................................................................... 6-10

71 Connecting to the Database....................................................................................................... 7-272 Unlocking the Database Account ............................................................................................. 7-273 Creating a New Project .............................................................................................................. 7-374 Setting Java Options ................................................................................................................... 7-475 Defining the Database Connection........................................................................................... 7-576 Creating EJB Entity Beans.......................................................................................................... 7-677 Specifying the EJB Version ........................................................................................................ 7-778 Defining the Persistence Unit.................................................................................................... 7-879 Creating Entity Beans from Table Data ................................................................................... 7-9710 Choosing the Database Connection ...................................................................................... 7-10711 Choosing the Table Data for the Entity Bean....................................................................... 7-11712 Choosing General Options for the Entity............................................................................. 7-12713

Specifying the Entity Details ..................................................................................................7-13

714 Entity Bean Summary Page .................................................................................................... 7-14715 Generating EJB Entity Beansthe EJB Log Window ......................................................... 7-14716 Adding a JPA Cache Configuration to the Runtime Configuration................................. 7-18717 Adding JARs and Libraries to the Classpath ....................................................................... 7-19718 Creating a Java Class ............................................................................................................... 7-19719 Results from the RunEmployeeExample Application........................................................ 7-2181 Creating a Project ........................................................................................................................ 8-382 Creating a Java Class .................................................................................................................. 8-383 Creating an XML File ................................................................................................................. 8-4


10/178

x

84 Adding the Oracle JDBC Libraries to the Classpath.............................................................. 8-585 Setting the Cache Configuration File for Runtime Options.................................................. 8-686 Output from the CoherenceCache Program ........................................................................... 8-887 Creating a Table in the Oracle Database.................................................................................. 8-988 Creating a Java Class ............................................................................................................... 8-1089 Creating a Java Class ............................................................................................................... 8-15810 Results from Running the DatabaseCache Application..................................................... 8-19

811 Updates to Database Tables ................................................................................................... 8-20


11/178

xi

Preface

Oracle Coherence is an in-memory data grid solution that enables organizations topredictably scale mission-critical applications by providing fast access to frequentlyused data. Data grid software is a middleware that reliably manages data objects inmemory across many servers. By automatically and dynamically partitioning data,Oracle Coherence enables continuous data availability and transactional integrity, evenin the event of a server failure. Oracle Coherence provides organizations with a robust,

scale-out data abstraction layer.

Developers can easily take advantage of the features of Coherence using the standardJava collections API to access and modify data, and use the standard JavaBean eventmodel to receive data change notifications.

AudienceThis book is targeted at software developers, architects, and administrators. Itprovides a brief overview of the Oracle Coherence data grid, installation,configuration, developing with, and finally deploying Oracle Coherence.

Documentation AccessibilityOur goal is to make Oracle products, services, and supporting documentationaccessible to all users, including users that are disabled. To that end, ourdocumentation includes features that make information available to users of assistivetechnology. This documentation is available in HTML format, and contains markup tofacilitate access by the disabled community. Accessibility standards will continue toevolve over time, and Oracle is actively engaged with other market-leadingtechnology vendors to address technical obstacles so that our documentation can beaccessible to all of our customers. For more information, visit the Oracle AccessibilityProgram Web site at http://www.oracle.com/accessibility/ .

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. Theconventions for writing code require that closing braces should appear on anotherwise empty line; however, some screen readers may not always read a line of textthat consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies ororganizations that Oracle does not own or control. Oracle neither evaluates nor makesany representations regarding the accessibility of these Web sites.


12/178

xii

TTY Access to Oracle Support Services

To reach AT&T Customer Assistants, dial 711 or 1.800.855.2880. An AT&T CustomerAssistant will relay information between the customer and Oracle Support Services at1.800.223.1711. Complete instructions for using the AT&T relay services are available athttp://www.consumer.att.com/relay/tty/standard2.html . After theAT&T Customer Assistant contacts Oracle Support Services, an Oracle SupportServices engineer will handle technical issues and provide customer support according

to the Oracle service request process.

Related DocumentsFor more information, see the following documents in the Oracle Coherencedocumentation set:

Getting Started with Oracle Coherence

User's Guide for Oracle Coherence

Developer's Guide for Oracle Coherence

ConventionsThe following text conventions are used in this document:

Convention Meaning

boldface Boldface type indicates graphical user interface elements associatedwith an action, or terms defined in text or the glossary.

italic Italic type indicates book titles, emphasis, or placeholder variables forwhich you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, codein examples, text that appears on the screen, or text that you enter.


13/178

1

Installing Coherence and JDeveloper 1-1

1Installing Coherence and JDeveloper

This chapter describes how to install and set up your environment for running OracleJDeveloper Studio Edition 11g and Oracle Coherence 3.4.x. This chapter contains thefollowing sections:

Downloading and Installing Coherence

Downloading and Installing JDeveloper

Testing a Coherence Installation

This chapter assumes that you have the privileges to install software and set systemenvironment variables as the oracle user, an understanding of how to use a terminalwindow, including setting environment variables, and creating and moving betweendirectories. It also assumes that you have a working installation of Java SE (JDK)version 1.6.

Downloading and Installing CoherenceTo download and install Oracle Coherence:

1. Download Oracle Coherence 3.4.x to your desktop.

Coherence (Java edition) ships as a single zip file, typically calledcoherence-.zip. You can obtain Coherence 3.4.x from the followingURL:

http://www.oracle.com/technology/products/coherence/index.htm

l

2. Extract the contents of the zip file to a directory named C:\oracle\product.

The zip file contains the coherence directory with these subdirectories:

bincontains command scripts

libcontains the required library files

examples contains the example code

doccontains the product documentation

Downloading and Installing JDeveloperTo download and Install Oracle JDeveloper Studio Edition 11g:

1. Download Oracle JDeveloper Studio.

You can obtain JDeveloper Studio 11g from the following URL:


14/178


1-2 Oracle Coherence Tutorial for Oracle Coherence

http://www.oracle.com/technology/products/jdev/index.html

2. Run the JDeveloper Studio installer.

Follow the prompts in the installation screens. If the installer asks for aMiddleware Home, enter C:\oracle\productif it does not already exist.

If you are asked for a User Rolewhen JDeveloper starts, select Default Roleto

enable all technologies.

Testing a Coherence InstallationIn this exercise, you test whether your Coherence installation can cluster Javaprocesses together. This will ensure that Coherence-based applications that ship withCoherence will run as expected. If Coherence is not capable of clustering on a singlemachine, then you will need to reconfigure your network and firewall settings.

This exercise assumes that you have installed Oracle Coherence (Java Edition) 3.4.1(See "Downloading and Installing Coherence"on page 1-1).

Coherence uses a variety of network addresses and ports to enable communicationbetween clustered processes. If these addresses and/or ports are unavailable due to

other applications using them, or because of a firewall, then Coherence may beunreliable, may fail to cluster, or may not work at all. By default, Coherence assumesthat the network addresses and ports listed in Table 11are available:

Coherence ships with two simple command-line (shell-based) applications that can beused to determine whether Coherence will operate correctly.

The "cache server," is a simple application that hosts and manages data on behalfof other applications in a cluster.

The "coherence shell," is a simple application that enables a developer to access,process, and update cached data within a cluster. It also provides informaitonabout the cluster. By executing these applications on either a single host or severalhosts, you can determine whether Coherence is operating correctly locally oracross a network.

When an application uses Coherence out-of-the-box, objects placed into Coherencecaches are typically stored and managed in-process within the application.

However, to increase the availability of the objects, Coherence may manage objectsin-memory but out of the application process. This allows objects to survivepossible application outages (either deliberate or accidental). To manage objects inthis way, Coherence uses "Cache Servers". The purpose of a Coherence cacheserver is to manage application state in a cluster outside the application process. Itis much like a database server, but without the requirement for storage.

To set up and run the cache server and client:

1. Open a terminal window and verify that the PATHenvironment variable is set toinclude \oracle\product\jdk160_05\bin. If the PATHenvironment variabledoes not include jdk\jdk160_05\bindirectory, then set the variable as follows:

Table 11 Network Addresses and Ports Used by Coherence

Address / Port / Type Purpose

224.3.3.1/ 33389/ Multicast Cluster member discovery and broadcast

localhost/ 8088+/ Unicast Inter-process communication between cluster members.(localhostis the local IP address and not the loop

back address.)
http://-/?-http://-/?-


15/178



a. Set the JAVA_HOMEenvironment variable to the base of the JDK installation.

set JAVA_HOME=\oracle\product\jdk160_05

b. Include JAVA_HOME\binin the PATHenvironment variable.

set PATH=%JAVA_HOME%\bin;%PATH%

2. Navigate to the directory where Coherence is installed. Edit cache-server.cmdand set the COHERENCE_HOMEvariable to point to the Coherence installationdirectory.

cd C:\oracle\product\coherence\bin

In cache-server.cmd, set the COHERENCE_HOMEenvironment variable:

COHERENCE_HOME=C:\oracle\product\coherence

Save cache-server.cmdand close the file.

Example 11illustrates cache-server.cmdwith the edited value ofCOHERENCE_HOME.

Example 11 cache-server.cmd File with an Edited COHERENCE_HOME

@echo off

@

@rem This will start a cache server

@

setlocal

:config

@rem specify the Coherence installation directory

set coherence_home=c:\oracle\product\coherence

@rem specify the JVM heap size

set memory=512m

:start

if not exist "%coherence_home%\lib\coherence.jar" goto instructions

if "%java_home%"=="" (set java_exec=java) else (set java_exec=%java_

home%\bin\java)

:launch

set java_opts="-Xms%memory% -Xmx%memory%"

"%java_exec%" -server -showversion "%java_opts%" -cp "%coherence_

home%\lib\coherence.jar" com.tangosol.net.DefaultCacheServer %1

goto exit

:instructions

echo Usage:

echo ^\bin\cache-server.cmd

goto exit

:exit

endlocal

@echo on


16/178



3. Execute the cache server application that is located in the coherence\bindirectory.

C:\oracle\product\coherence\bin>cache-server.cmd

When you start the first cache server, there is a slight delay because the cacheserver looks for an existing cluster. When it determines that there are no clusters to

join, it starts one. On startup, the cache server will produce output similar to thecode in Example 12.

Several important features are highlighted in the example:

the Java JDK version number: java version "1.6.0_05"

information about how configuration files are loaded. The default is to loadfrom JAR: Loaded operational configuration from resource"jar:file:/C:/oracle/product/coherence/lib/coherence.jar!/

tangosol-coherence.xml"

the Coherence version number: Oracle Coherence Version 3.4.1/407

the multicast address. This address changes with each Coherence version.

Note the 3.4.1in the address for Coherence version 3.4.1:Group{Address=224.3.4.1, Port=34407, TTL=4}

the Member Id indicates the number of members in your cluster. For thepurposes of this exercise, the value should be 1. ThisMember=Member(Id=1...

Example 12 Output from Starting a Coherence Cache Server

C:\oracle\product\coherence\bin>cache-server.cmd

java version "1.6.0_05"

Java(TM) SE Runtime Environment (build 1.6.0_05-b13)

Java HotSpot(TM) Server VM (build 10.0-b19, mixed mode)

2008-12-09 14:29:11.968/1.391 Oracle Coherence 3.4.1/407 (thread=main, member=n/a):Loaded operational configuration from resource "jar:file:/C:/oracle/p

roduct/coherence/lib/coherence.jar!/tangosol-coherence.xml"

2008-12-09 14:29:11.983/1.406 Oracle Coherence 3.4.1/407 (thread=main, me

mber=n/a): Loaded operational overrides from resource "jar:file:/C:/oracle/produ

ct/coherence/lib/coherence.jar!/tangosol-coherence-override-dev.xml"

2008-12-09 14:29:11.983/1.406 Oracle Coherence 3.4.1/407 (thread=main, memb

er=n/a): Optional configuration override "/tangosol-coherence-override.xml" is n

ot specified


er=n/a): Optional configuration override "/custom-mbeans.xml" is not specified

Oracle Coherence Version 3.4.1/407

Grid Edition: Development mode

Copyright (c) 2000-2008 Oracle. All rights reserved.

2008-12-09 14:29:12.827/2.250 Oracle Coherence GE 3.4.1/407 (thread=main,

member=n/a): Loaded cache configuration from resource "jar:file:/C:/oracle/prod

uct/coherence/lib/coherence.jar!/coherence-cache-config.xml"

2008-12-09 14:29:14.093/3.516 Oracle Coherence GE 3.4.1/407 (thread=Cluster

, member=n/a): Service Cluster joined the cluster with senior service member n/a

2008-12-09 14:29:17.343/6.766 Oracle Coherence GE 3.4.1/407 (thread=Clust

er, member=n/a): Created a new cluster "cluster:0x23CB" with Member(Id=1, Timest

amp=2008-12-09 14:29:13.702, Address=130.35.99.248:8088, MachineId=49912, Locati

on=site:us.oracle.com,machine:tpfaeffl-pc,process:4440, Role=CoherenceServer, Ed


17/178



ition=Grid Edition, Mode=Development, CpuCount=1, SocketCount=1) UID=0x822363F80

000011E1DDE4966C2F81F98

2008-12-09 14:29:17.671/7.094 Oracle Coherence GE 3.4.1/407 (thread=Distrib

utedCache, member=1): Service DistributedCache joined the cluster with senior se

rvice member 1

2008-12-09 14:29:17.827/7.250 Oracle Coherence GE 3.4.1/407 (thread=Replica

tedCache, member=1): Service ReplicatedCache joined the cluster with senior serv

ice member 1

2008-12-09 14:29:17.843/7.266 Oracle Coherence GE 3.4.1/407 (thread=Optimis

ticCache, member=1): Service OptimisticCache joined the cluster with senior serv

ice member 1

2008-12-09 14:29:17.858/7.281 Oracle Coherence GE 3.4.1/407 (thread=Invocat

ion:InvocationService, member=1): Service InvocationService joined the cluster w

ith senior service member 1

2008-12-09 14:29:17.874/7.297 Oracle Coherence GE 3.4.1/407 (thread=main,

member=1): Started DefaultCacheServer...

SafeCluster: Name=cluster:0x23CB

Group{Address=224.3.4.1, Port=34407, TTL=4}

MasterMemberSet

(

ThisMember=Member(Id=1, Timestamp=2008-12-09 14:29:13.702, Address=130.35.99.2

48:8088, MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-pc,proces

s:4440, Role=CoherenceServer)

OldestMember=Member(Id=1, Timestamp=2008-12-09 14:29:13.702, Address=130.35.99

.248:8088, MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-pc,proc

ess:4440, Role=CoherenceServer)

ActualMemberSet=MemberSet(Size=1, BitSetCount=2

Member(Id=1, Timestamp=2008-12-09 14:29:13.702, Address=130.35.99.248:8088,

MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-pc,process:4440, R

ole=CoherenceServer)

)

RecycleMillis=120000 RecycleSet=MemberSet(Size=0, BitSetCount=0

)

)

Services

(

TcpRing{TcpSocketAccepter{State=STATE_OPEN, ServerSocket=130.35.99.248:8088},

Connections=[]}

ClusterService{Name=Cluster, State=(SERVICE_STARTED, STATE_JOINED), Id=0, Vers

ion=3.4, OldestMemberId=1}

DistributedCache{Name=DistributedCache, State=(SERVICE_STARTED), LocalStorage=

enabled, PartitionCount=257, BackupCount=1, AssignedPartitions=257, BackupPartit

ions=0}

ReplicatedCache{Name=ReplicatedCache, State=(SERVICE_STARTED), Id=2, Version=3.0, OldestMemberId=1}

Optimistic{Name=OptimisticCache, State=(SERVICE_STARTED), Id=3, Version=3.0, O

ldestMemberId=1}

InvocationService{Name=InvocationService, State=(SERVICE_STARTED), Id=4, Versi

on=3.1, OldestMemberId=1}

)


18/178



The output of cache-server.cmdindicates whether you have one or more

members in your cluster. The value of Member ID should be equal to 1:...

In MasterMemberSet

ThisMember=Member(Id should be equal to 1)

...

If Member ID is greater than 1, then multiple clusters are being formed in yoursubnet. For the purposes of these exercises, there should only be one member inthe cluster. Follow the steps in "Restricting Coherence to Your Own Host"onpage 1-12to restrict Coherence to your own host.

4. Open another terminal window to run the cache client.

Verify that the PATHenvironment variable is set to include

\oracle\product\jdk160_05\bin. If the PATHenvironment variable doesnot include the jdk160_05\bindirectory, then set the variable as follows:



b. Include JAVA_HOME\binin the PATHenvironment variable.


5. Navigate to the \oracle\product\coherence\bindirectory. Editcoherence.cmdand set the COHERENCE_HOMEvariable to point to theCoherence installation directory. Save and close the file.

Example 13illustrates the coherence.cmdfile, with COHERENCE_HOME=\oracle\product\coherence.

Example 13 coherence.cmd File with an Edited COHERENCE_HOME

@echo off

@

@rem This will start a console application

@rem demonstrating the functionality of the Coherence(tm) API

@

setlocal

:config

@rem specify the Coherence installation directory

set coherence_home=c:\oracle\product\coherence

@rem specify if the console will also act as a server

set storage_enabled=false

@rem specify the JVM heap size

set memory=64m

:start

if not exist "%coherence_home%\lib\coherence.jar" goto instructions

Note: By default, Coherence uses multicast only to search for clustermembers. Multicast is not used for data transfer. If you cannot use ordo not want to use multicast, this can be configured.


19/178



if "%java_home%"=="" (set java_exec=java) else (set java_exec=%java_

home%\bin\java)

:launch

if "%storage_enabled%"=="true" (echo ** Starting storage enabled console **) else

(echo ** Starting storage disabled console **)

set java_opts="-Xms%memory% -Xmx%memory%

-Dtangosol.coherence.distributed.localstorage=%storage_enabled%"

"%java_exec%" -server -showversion "%java_opts%" -cp "%coherence_

home%\lib\coherence.jar" com.tangosol.net.CacheFactory %1

goto exit

:instructions

echo Usage:

echo ^\bin\coherence.cmd

goto exit

:exit

endlocal

@echo on

6. Execute the coherence.cmdfile to start the cache client. This application showsyou the basic distributed cache functionality that is built within Coherence.

coherence.cmd

Example 14illustrates the output from starting the cache client. Note thefollowing features of the output:

the client is the second member of the cluster (the server is the first member):ThisMember=Member(Id=2,...

at the end of the output, you should see theMap(?)prompt

Example 14 Output from Starting the Coherence Cache Client

** Starting storage disabled console **

java version "1.6.0_05"

Java(TM) SE Runtime Environment (build 1.6.0_05-b13)

Java HotSpot(TM) Server VM (build 10.0-b19, mixed mode)


mber=n/a): Loaded operational configuration from resource "jar:file:/C:/oracle/p

roduct/coherence/lib/coherence.jar!/tangosol-coherence.xml"


mber=n/a): Loaded operational overrides from resource "jar:file:/C:/oracle/product/coherence/lib/coherence.jar!/tangosol-coherence-override-dev.xml"


er=n/a): Optional configuration override "/tangosol-coherence-override.xml" is n

ot specified


er=n/a): Optional configuration override "/custom-mbeans.xml" is not specified

Oracle Coherence Version 3.4.1/407

Grid Edition: Development mode

Copyright (c) 2000-2008 Oracle. All rights reserved.


20/178




, member=n/a): Service Cluster joined the cluster with senior service member n/a


er, member=n/a): Failed to satisfy the variance: allowed=16, actual=125


er, member=n/a): Increasing allowable variance to 29


er, member=n/a): This Member(Id=2, Timestamp=2008-12-09 19:35:57.046, Address=13

0.35.99.248:8089, MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-

pc,process:4716, Role=CoherenceConsole, Edition=Grid Edition, Mode=Development,

CpuCount=1, SocketCount=1) joined cluster "cluster:0x23CB" with senior Member(Id

=1, Timestamp=2008-12-09 18:30:10.436, Address=130.35.99.248:8088, MachineId=499

12, Location=site:us.oracle.com,machine:tpfaeffl-pc,process:4148, Role=Coherence

Server, Edition=Grid Edition, Mode=Development, CpuCount=1, SocketCount=1)


, member=n/a): Member 1 joined Service DistributedCache with senior member 1


, member=n/a): Member 1 joined Service ReplicatedCache with senior member 1


, member=n/a): Member 1 joined Service OptimisticCache with senior member 1


, member=n/a): Member 1 joined Service InvocationService with senior member 1

SafeCluster: Name=cluster:0x23CB

Group{Address=224.3.4.1, Port=34407, TTL=4}

MasterMemberSet

(

ThisMember=Member(Id=2,Timestamp=2008-12-09 19:35:57.046, Address=130.35.99.2

48:8089, MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-pc,proces

s:4716, Role=CoherenceConsole)

OldestMember=Member(Id=1, Timestamp=2008-12-09 18:30:10.436, Address=130.35.99

.248:8088, MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-pc,proc

ess:4148, Role=CoherenceServer)

ActualMemberSet=MemberSet(Size=2, BitSetCount=2 Member(Id=1, Timestamp=2008-12-09 18:30:10.436, Address=130.35.99.248:8088,


ole=CoherenceServer)



ole=CoherenceConsole)

)

RecycleMillis=120000

RecycleSet=MemberSet(Size=0, BitSetCount=0

)

)

Services

( TcpRing{TcpSocketAccepter{State=STATE_OPEN, ServerSocket=130.35.99.248:8089},

Connections=[]}

ClusterService{Name=Cluster, State=(SERVICE_STARTED, STATE_JOINED), Id=0, Vers

ion=3.4, OldestMemberId=1}

)

Map (?):

2008-12-09 19:35:58.280/4.047 Oracle Coherence GE 3.4.1/407 (thread=TcpRing

Listener, member=2): TcpRing: connecting to member 1 using TcpSocket{State=STATE

_OPEN, Socket=Socket[addr=/130.35.99.248,port=2115,localport=8089]}


21/178



Map (?):

7. Exercise the client application by executing the following Coherence commands inthe Coherence shell:

Enter helpto see the list of commands that are available.

Enter cache mycache.The cachemycacheimplements the com.tangosol.net.NamedCacheinterface. Each NamedCachecan be thought of as a table. A cluster can havemany named caches. Each NamedCacheholds one type of object. It can be asimple object, such as a String, or a complex object that you define.

Example 15illustrates that using the default configuration files(coherence-cache-config.xml) within the supplied coherence.jarfile, a NamedCachecalledmycacheis created using the distributed scheme:

Example 15 Output from Starting a Coherence Cache

Map (?): cache mycache

2008-12-09 19:46:02.889/608.656 Oracle Coherence GE 3.4.1/407 (thread=mai

n, member=2): Loaded cache configuration from resource"jar:file:/C:/oracle/prod

uct/coherence/lib/coherence.jar!/coherence-cache-config.xml"

2008-12-09 19:46:03.421/609.188 Oracle Coherence GE 3.4.1/407 (thread=Distr

ibutedCache, member=2): Service DistributedCache joined the cluster with senior

service member 1

2008-12-09 19:46:03.452/609.219 Oracle Coherence GE 3.4.1/407 (thread=Distr

ibutedCache, member=2): Service DistributedCache: received ServiceConfigSync con

taining 258 entries

example-distributed

DistributedCache

example-binary-backing-map

true

Map (mycache):

Execute the following commands at the Map(?)prompt in the Coherenceshell:

getmessageretrieves the value for the given key from the named cache

putmessage"hello"puts a name/value pair (key and value) into thecache. This command always returns the last value assigned to the key.

listdisplays the contents of the named cache


22/178



size

getmessage

putmessage"second message"

getmessage

removemessageremoves a key value from the cache

size

getmessage

putmessage"hi"

bye

Example 16illustrates the output of each of these commands.

Example 16 Exercising Coherence Commands

Map (mycache): get message

null

Map (mycache): put message "hello"

null

Map (mycache): list

message = hello

Map (mycache): size

1


hello

Map (mycache): put message "second message"

hello


second message

Map (mycache): remove message

second message

Map (mycache): size

0


null

Map (mycache): put message "hi"

null

Map (mycache): bye

2008-12-10 11:17:18.921/56484.688 Oracle Coherence GE 3.4.1/407 (thread=Dis

tributedCache, member=2): Service DistributedCache left the cluster

2008-12-10 11:17:19.061/56484.828 Oracle Coherence GE 3.4.1/407 (thread=Clu

ster, member=2): Service Cluster left the cluster

C:\oracle\product\coherence\bin>


23/178



8. Open another terminal window and set the PATHenvironment variable to include\oracle\product\jdk160_05\bin. and the JAVA_HOMEvariable to\oracle\product\jdk160_05(See Step 4).

9. Start a second instance of coherence.cmdin the new terminal window. Notethat a message similar to the following will be displayed in the terminal windowwhere the first client is running:

Map (mycache):2008-12-10 11:51:15.468/66.407 Oracle Coherence GE 3.4.1/407 (thread=Cluster,

member=3): Member 4 joined Service DistributedCache with senior member 1

10. Use the cache mycachecommand in the new terminal to connect to theNamedCachecalledmycache. Try to get and put values in different sessions.notice that each client can observe changes made by the other client.

11. Close down one of the coherence.cmdconsoles. Note that a message indicatingthat the member has left the cluster will appear on the other console. For example:

Map (mycache):

2008-12-10 12:00:09.139/600.078 Oracle Coherence GE 3.4.1/407

(thread=Cluster, member=3): Member 4 left service DistributedCache with senior

member 1

Map (mycache):


(thread=Cluster, member=3): MemberLeft notification for Member 4 received from


MachineId=49912, Location=site:us.oracle.com,machine:tpfaeffl-pc,process:5356,

Role=CoherenceConsole)


(thread=Cluster, member=3): Member(Id=4, Timestamp=2008-12-10 12:00:09.249,

Address=130.35.99.248:8090, MachineId=49912,

Location=site:us.oracle.com,machine:tpfaeffl-pc,process:5356,

Role=CoherenceConsole) left Cluster with senior member 1

12. If you close each of the Coherence shells (bye), and then restart them, note thatdata from the previous session still available. This is because the data is held in thecache server.

13. If you run another Coherence cache server, and then kill the initial one that wasstarted (using Ctrl+Cor by closing the Command Console window), is data stillavailable from the Coherence shells? Why?

14. Shut down both the coherence.cmdconsoles and cache-server.cmd. Startcoherence.cmd. Create a NamedCachecalled testusing cachetest. Try toput in a value as before. What happens and why?

15. Start up a cache server by running the cache-server.cmdfile from thecoherence\bindirectory. Try to put in a value again. What happens and why?

16. Shut down all the cache servers.

Troubleshooting Cache Server Clustering

If the value of Member ID in the cache-server.cmdoutput is anything other than 1,then this indicates that the cache server has clustered with one or more other cacheservers or processes running Coherence. These servers or processes may be running onthe network or running locally on your host. Though this is default behavior forCoherenceto cluster with other processes running Coherence locally or on anetworkit is strongly advised that you restrict Coherence to your own host.


24/178



Restricting Coherence to Your Own Host

The output of cache-server.cmdindicates whether you have just one member inyour cluster. The value of Member ID should be equal to 1:

...

In MasterMemberSet

ThisMember=Member(Id should be equal to 1)

...

If Member ID is greater than 1, it means that multiple clusters are being formed inyour subnet. For the purposes of the exercises in this document, there should only beone member in the cluster.

To restrict Coherence to your own host:

1. Stop cache server by pressing Ctrl+C.

2. Create a directory called backupunder oracle\product\coherence\lib.

cd C:\oracle\product\coherence\lib

mkdir backup

3.Copy

coherence.jarfrom the

oracle\product\coherence\libdirectoryto the backupdirectory.

cp coherence.jar C:\oracle\product\coherence\lib\backup\coherence.jar

4. Navigate to the oracle\product\coherence\lib\backup directory.

5. Extract tangosol-coherence.xmlfrom coherence.jar.

jar -xvf coherence.jar tangosol-coherence.xml

6. Edit the tangosol-coherence.xmlfile.

Change the multicast listener port to a unique value, for example, 34408. Be surethat your multicast listener port value that you are setting is unique. For example,

if you share the port value34407

with another user, then change your port valueto 34408 and the other user can change to 34409. When you are finished, save thefile and quit the editor.

Example 17illustrates themulticast-listenerfragment oftangosol-coherence.xmlwith its original port value of 34407.

Example 17 Multicast-Listener Fragment of tangosol-coherence.xml File

...

224.3.4.1

34407

4


25/178



7. Append the modified tangosol-coherence.xmlfile to coherence.jarin thebackupdirectory. Replace coherence.jarin the libdirectory with the one inthe backupdirectory.

jar -uvf coherence.jar tangosol-coherence.xml

cp coherence.jar \oracle\product\coherence\lib\coherence.jar

When you execute cache-server.cmd, you should be able to view the modifiedport. Also, your cluster should now be restricted to your own host. If MembershipID still displays something other than 1, then there may be additional issues withthe installation. See "Advanced Steps to Restrict Coherence to Your Own Host"formore information.

Advanced Steps to Restrict Coherence to Your Own Host

If you follow the steps in the previous section and cache-server.cmdstill fails toreturn a Member Id value of 1, then there may be additional issues you must resolve.

Disconnect from the network or disable networking on your host. If errors orexceptions occur when starting the cache server, your network settings may need to bemodified. Try each of the following one at a time, restarting the cache server between

each attempt: If connected to a VPN, disconnect from it. By default, most VPN networks are not

configured to permit multicast and some unicast traffic. In this environment,Coherence may not work as it is configured out-of-the-box. Coherence can beconfigured to run across a VPN, but this requires some advanced settings.

If you are running a firewall, configure it to allow the specified addresses andports.

If you still experience problems, unplug or disconnect from all the networks. Thisincludes wireless and wired networks.

If all the preceding options fail, set up Coherence to run on a single host.


26/178




27/178

2

Using JDeveloper with Coherence 2-1

2Using JDeveloper with Coherence

This chapter describes how to set up JDeveloper to build and run Coherence-basedJava applications.

Configuring Oracle JDeveloper for Coherence

Accessing the Data Grid from Java

Creating Your First Coherence-Based Java Application

Configuring Oracle JDeveloper for CoherenceTo start up and configure JDeveloper for use with Coherence:

1. Open a terminal window and verify that the PATHenvironment variable is set toinclude \oracle\product\jdk160_05\bin. If the PATHenvironment variabledoes not include jdk160_05\bindirectory, then set the variable as follows:



b. Include %JAVA_HOME%\binin the PATH environment variable.


c. Start JDeveloper. If you get a message asking you to select a role, selectDefault Role. If you get a message asking whether you want to migrate fromprevious versions of JDeveloper, select No. Close any window that displaysthe Tip of the Day."


28/178



Figure 21 Select Role Dialog Box

2. After JDeveloper starts up, click NewApplicationto create an application.

An application is a way of grouping projects or source code. This new applicationwill hold the Coherence projects.

3. In the dialog box, change the application name to Coherence, the directory to\home\oracle\labs, and the application package prefix tocom.oracle.coherence.handson. Click OK, and then click Cancelwhenprompted to create a new project.


29/178



Figure 22 Creating an Application in JDeveloper

4. Add the Coherence JAR files to the default project properties. From the Toolsmenu, select DefaultProjectProperties. The DefaultPropertiesdialog box opens.


30/178



Figure 23 Default Properties Dialog Box

5. Click Libraries and Classpath, and click the AddLibrarybutton. The AddLibrarydialog box opens.


31/178



Figure 24 Add Library Dialog Box

6. In the AddLibrarydialog box, click New.

The CreateLibrarydialog box opens.


32/178



Figure 25 Create Library Dialog Box

7. Click AddEntryto open the SelectPathEntrydialog box.

Find and expand the coherence\libdirectory, which is under the\oracle\productdirectory.

8. Highlight and select the coherence.jarfile add it to the Classpath. Then, clickOKto return to the CreateLibrarydialog box.


33/178



Figure 26 Select Path Entry Dialog Box

9. In the CreateLibrarydialog box, change the name in the LibraryNamefield toCoherence. The contents of the dialog box should look like this:


34/178



Figure 27 Create Library Dialog Box with the Coherence Jar on the Classpath

10. Click OKin the CreateLibrary, AddLibrary, and DefaultProjectProperties

dialog boxes to return to the JDeveloper IDE. Oracle JDeveloper is now set up withthe correct Coherence libraries.

Accessing the Data Grid from JavaIn this exercise, you develop a simple, Java console-based application to access,update, and remove simple types of information from a Coherence clustered cache.You also get familiar with using the Coherence Java APIs. In this practice, using

JDeveloper, you perform the following:

Create a new project

Create a new NamedCache

Put information into the cache and then retrieve it

Retrieve information about the cache

All Coherence caches are named, have a lifetime scoped by the cluster instance inwhich they exist, and implement the com.tangosol.net.NamedCacheinterface.The NamedCacheinterface is an extension of java.util.Mapand holds data andresources that are shared among the cluster members. Each NamedCacheholds dataas key/value pairs. Keys and values can be both simple and complex object types. TheNamedCacheinterface provides extensions to the Mapinterface, such as locking andsynchronization, storage integration, queries, event aggregations, and transactions.


35/178



The cache topology (or implementation) can be swapped or changed without codechanges. Table 21describes some of the more commonly used methods within theNamedCacheinterface:

The com.tangosol.net.CacheFactoryclass is typically used to obtain aninstance of a NamedCache. Table 22describes some of the more commonly usedmethods in the CacheFactoryclass.

For a full list of methods, in the NamedCacheinterface and the CacheFactoryclass,see the Javadoc in \oracle\product\coherence\doc.

To create an application to access, update, and remove simple types of informationfrom a Coherence clustered cache:

1. Create a new project in JDeveloper.

a. Choose File > New...in the JDeveloper IDE. This will open the NewGallery.

Choose General > Projectsin the Categoriessection of the NewGallerydialog box and GenericProjectin the Itemssection. Click OK.

Table 21 Methods in the NamedCache Interface

Method Name Description

voidclear() Removes all entries from the NamedCache

boolean containsKey(Object

key)

Returns trueif NamedCachecontains an entry for thekey

boolean

containsValue(Objectvalue)

Returns trueif there is at least one entry with this valuein NamedCache

Object get(Object key) Gets the entry from NamedCachefor that key

Object put(Object

key,Objectvalue)

Puts an object in NamedCache(blocking call)

Object remove(Object key) Removes the mapping for this keyfrom this map ifpresent. Inherited from ConcurrentMap.

Set entrySet() Returns a set of key/value pairs

Collection values() Gets all values back as a collection

CacheService

getCacheService()

Returns the CacheServicethat this NamedCacheis apart of.

Table 22 Methods in the CacheFactory Class

Method Name Description

static Cluster

ensureCluster()

Obtains a cluster object running Coherence services

static void shutdown() Shuts down all clustered services

static NamedCache

getCache(String cache)

Returns an instance of a cache. Either joins an existingcache in the cluster or creates the cache if this is the firstmember.
http://-/?-http://-/?-http://-/?-http://-/?-


36/178



Figure 28 Choosing Projects in the New Gallery

b. In the CreateGenericProjectdialog box, name the project Lab3. Ensure thatdirectory is C:\home\oracle\labs\Lab3. Click Finish.


37/178



Figure 29 Providing Project Details

2. Create your first Coherence Java program.

a. Right-click the Lab3project entry and select New.

b. Select the Generalcategory and selectJavaClass. Click OK.

c. Enter MyFirstSampleas the class name and select the GenerateMainMethodcheck box. The dialog box should appear as follows. Click OK.

Figure 210 Providing Java Class Details


38/178



d. Right-click the Lab3project and choose Project Properties. Select Librariesand Classpathin the ProjectPropertiesdialog box. You should see theCoherence library that you defined earlier included here by default. ClickCancelto dismiss the dialog box.

e. In the editor for MyFirstSample, you must import the followingcomponents into your Java class:

import com.tangosol.net.CacheFactory;import com.tangosol.net.NamedCache;

f. Write the code to create a NamedCache, put in a value, and then verify thevalue that you put in. Save the file after you finish coding. Example 21illustrates a sample program.

Example 21 Creating a NamedCache; Inserting and Verifying Values

package com.oracle.coherence.handson;

import com.tangosol.net.CacheFactory;

import com.tangosol.net.NamedCache;

public class MyFirstSample {

public MyFirstSample() {

}

public static void main(String[] args) {

// ensure we are in a cluser

CacheFactory.ensureCluster();

// create or get a named cache called mycache

NamedCache myCache = CacheFactory.getCache("mycache");

// put key, value pair into the cache.

myCache.put("Name","Tim Middleton");

System.out.println("Value in cache is " + myCache.get("Name"));

}

}

g. Run the program in JDeveloper: right-click the MyFirstSample.javaclassin the editor and choose Run.

h. You should see messages similar to the following:


39/178



Figure 211 Output of Program to Create a NamedCache and to Store and Retrieve Values

3. Now create another Java class only to get the value from your cache, rather thandoing a put, and then a get. Name this Java class MyFirstSampleReader.Example 22illustrates a sample program.

Example 22 Getting a Value from the Cache




public class MyFirstSampleReader {

public MyFirstSampleReader() {

}


// ensure we are in a cluser


// create or get a named cache called mycache


System.out.println("Value in cache is " + myCache.get("Name"));

}

}

Run the MyFirstSampleReaderclass. Figure 212illustrates the output from theprogram. Note that a null value returned. When the MyFirstSampleclass runs, itis storage-enabled by default unless otherwise specified. So, it creates aNamedCachewhen it starts, puts the value in, and when the class completes, theNamedCachedisappears.


40/178



Figure 212 Output from the Sample Reader Program

4. Start up the cache-server.cmdthat you used in "Testing a CoherenceInstallation"on page 1-2, run MyFirstSampleto put the value in theNamedCache, and then run MyFirstSampleReaderto read the value from thecache. Note the output illustrated in Figure 213: the "Gene Smith" value stored

by MyFirstSampleis returned by MyFirstSampleReader. By default, unlessspecified otherwise, all processes start up as storage-enabled. This means that theprocess can store data as part of the cluster.

Figure 213 Output from the Sample Reader Program with a Running Cache Server

This should not be the case for a process that joins the cluster only to perform anoperation, such as putting in a value and then leaving, like MyFirstSample. Youmust modify the process so that it will not be storage-enabled.

This is done using the following Java command-line parameter.


41/178



-Dtangosol.coherence.distributed.localstorage

The value -Dtangosol.coherence.distributed.localstorage=true specifies that the process is storage-enabled. Setting the parameter to falsespecifies that the process is not storage-enabled.

a. Right-click the Lab3project and select ProjectProperties.

b. Choose Run/Debug/Profileand click Edit.

c. Ensure the VirtualMachinefield is set to server.

d. Enter the following value in the Java Options field:

-Dtangosol.coherence.distributed.localstorage=false

-Dtangosol.coherence.log.level=3

The screen should look similar to the illustration in Figure 214.

Figure 214 Editing Run Configuration Properties

e. Click OK, and then OKin the ProjectPropertiesdialog box save.5. Shut down any running cache servers and rerun your MyFirstSampleclass.

What happens? You receive a message similar to the one in Figure 215indicatingthat storage is not enabled on the cluster, because you have set this member to bestorage-disabled.


42/178



Figure 215 Output from JDeveloper if Storage is Disabled

6. Start the cache server again and retest. You should now see that the data ispersisted between running the two Java examples.

Creating Your First Coherence-Based Java ApplicationIn this practice you develop a simple Java console-based application to access update,and remove simple types of information from a Coherence clustered cache.

This practice assumes you have completed "Testing a Coherence Installation"onpage 1-2. Make sure you have a cache server and a Coherence console up and running.

Unlike client/server applications, in which client applications typically "connect" and"disconnect" from a server application, Coherence-based clustered applications simply"ensure" they are in a cluster, after which they may use the services of the cluster.Coherence-based applications typically do not "connect" to a cluster of applications;they become part of the cluster.

To change the level of logging produced by Coherence, use the following JVMparameter where levelis a number between 0 and 9:

-Dtangosol.coherence.log.level=level

The default is 5. A value of 0 means no logging. A value of 9 means extremely verbose.A value of 3 is often useful enough for most application development.

To create a Java console-based application to access update, and remove simple typesof information from a Coherence clustered cache:

1. In the Coherence Java documentation (Javadoc) that is shipped in the\oracle\product\coherence\docdirectory, investigate the methods in theCacheFactoryclass.

2. Develop a simple Java console application (Java class) calledYourFirstCoherenceApplicationthat uses the CacheFactoryclass to joina cluster (using the ensureClustermethod), and then leave the cluster (usingthe shutdownmethod).

3. Using the Javadoc, investigate the methods that are available in the NamedCacheinterface.

4. Extend your application to use the CacheFactorymethod getCacheto acquirea NamedCachefor the cache calledmycache(the same cache name used in theexercise: "Testing a Coherence Installation"on page 1-2).

5. With the NamedCacheinstance, use the "get" method to retrieve the value for thekey "message" (the same key used in the exercise: "Testing a CoherenceInstallation"on page 1-2).


43/178



6. Output the value to the standard out using the System.out.println(.)method.

Example 23illustrates a sample Coherence-based Java application:

Example 23 Sample Coherence-Based Java Application




public class YourFirstCoherenceApplication {

public YourFirstCoherenceApplication() {

}




String message = (String)myCache.get("message");

System.out.println(message);

CacheFactory.shutdown();

YourFirstCoherenceApplication yourfirstcoherenceapplication = new

YourFirstCoherenceApplication();

}

}

7. Ensure that you have the Coherence cache server and console up and running. Inthe console, connect to themycachecache. For example:

Map(?): cache mycache

8. Execute YourFirstCoherenceApplicationfrom the JDeveloper IDE andview the result.

Figure 216illustrates the output from YourFirstCoherenceApplication.The output indicates that there is no data in the cache for themessagekey.

Figure 216 Output from Coherence-Based Java ApplicationNo Value for the Key

9. Using the running Coherence shell, change the key "message." For example, enter

Map : put message "hello"

Rerun YourFirstCoherenceApplicationfrom the JDeveloper IDE to see thechanged values. Figure 217illustrates that cache now holds the value helloforthe keymessage.


44/178



Figure 217 Output from Coherence-Based Java ApplicationA Data Value for the Key

10. Rerun YourFirstCoherenceApplicationwith the following JVM parameter.Notice that the output is the same as the previous run.


11. Shut down your cache server and Coherence shell instances. Restart the cacheserver and then rerun YourFirstCoherenceApplication(with the preceding

JVM parameter set). Note the output is now null.

12. If you change the value of themessagekey in your application (using the putmethod), is the new value available through the Coherence shell?

a. For example, comment out the getmethod and add the putmethod.

//String message = (String)myCache.get("message");

String message = (String)myCache.put("message", "bye");

b. Run YourFirstCoherenceApplication.

c. Run the get command in the Coherence console.


You should see byeas the output.

13. Try setting the following JVM parameter and rerunningYourFirstCoherenceApplication. Note that it causes the application toreturn a null value since local storage is not enabled.



45/178

3

Leaving Strings Behind 3-1

3Leaving Strings Behind

In this chapter, you work with complex objects residing in the cache. UsingJDeveloper, you will create a new Personclass that is serializable, store and retrievePersonobjects in the cache, and serialize your own objects.

This chapter contains the following sections:

Introduction

Creating and Caching Complex Objects

Caching a Complex Object using Java Serialization

Caching a Complex Object using Coherence PortableObject

IntroductionUntil now you have been putting and getting Stringobjects as the value in aNamedCache. Many of the implementations of the getand putmethods in theCoherence Java API define the values and keys to be of type Object. For example:

public java.lang.Object get(java.lang.Object oKey)

public void put(java.lang.Object oKey, java.lang.Object oValue)

Any object can potentially be used as a value or key. This enables you to store complexobjects as values in the cache.

Because Coherence may need to send the object across the wire, the object must beserializable. Object serialization is the process of saving an object's state into asequence of bytes, and then rebuilding them into a live object at some future time. Forexample, objects that implement the java.io.Serializableinterface areserializable.

Coherence supplies its own class for high-performance serialization calledcom.tangosol.io.pof.PortableObject. This is up to six times faster than thestandard Serializableand the serialized result set is smaller.

Creating and Caching Complex ObjectsIn this exercise you will create a Personobject that has attributes of various datatypes, and a program that uses Java Serialization to put the object into the cache andretrieve it.

To create complex objects and place them in the cache:

1. Create a Personclass to store in the cache.


46/178



a. Create a new project in JDeveloper called Lab4. Hint: Right-click theCoherence application and choose New... In the NewGallerychoose Projectsunder Categoriesand GenericProjectunder Items. Click OK.

Figure 31 Creating a New Project in the New Gallery

b. Name the project Lab4and selectJavafrom ProjectTechnologies. Click Next.


47/178


Leaving Strings Behind 3-3

Figure 32 Naming the New Project

c. Ensure that the DefaultPackageis com.oracle.coher