Child pages
  • Data Locality API

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Include Page
documentation-navbar
documentation-navbar
Section
Column
width250px
{div:style=} {include:
Wiki Markup
Div
stylemargin-top:20px
Include Page
documentation-index
documentation-index
} {div}
Column
{div9:id=documentationcolumn} {include:HeaderBasic} h1. DSO Locality API {include:dsoCaveat_include} {toc:minLevel=2|maxLevel=2} h2. Introduction Working with clustered data can present additional challenges to applications which must manage this data across a series of application servers. Using [the data locality methods|#The Methods] available through the Terracotta Distributed Shared Objects (DSO) API's DsoCluster interface, you can meet these challenges by adding locality awareness to your application code. Adding locality awareness, or visibility, provides a number of advantages, including: * Making applications more efficient with respect to data location by allowing code to be optimized along locality of reference. * Exposing data access and usage patterns from within an application. * Facilitating data commitment and eviction operations by providing information on the real-time location of clustered data or its absence. * Allowing a cache to send work to the appropriate node by providing the location of data that requires processing. * Providing insight into the effectiveness of data partitioning techniques by verifying the distribution of clustered data. For more information on data structures, see the Terracotta [DSO Data Structures Guide]. h2. Usage Classes that are injected with cluster awareness can call data locality methods. The following code example shows the cluster-aware class {{ClusterAwareClass}} with a member, {{localityAwareFoo()}}, that calls the data locality method {{getNodesWithObjects()}}: {code}
Wiki Markup
Div
iddocumentationcolumn
Include Page
HeaderBasic
HeaderBasic

DSO Locality API

Include Page
dsoCaveat_include
dsoCaveat_include
Table of Contents
minLevel2
maxLevel2

Introduction

Working with clustered data can present additional challenges to applications which must manage this data across a series of application servers. Using the data locality methods available through the Terracotta Distributed Shared Objects (DSO) API's DsoCluster interface, you can meet these challenges by adding locality awareness to your application code. Adding locality awareness, or visibility, provides a number of advantages, including:

  • Making applications more efficient with respect to data location by allowing code to be optimized along locality of reference.
  • Exposing data access and usage patterns from within an application.
  • Facilitating data commitment and eviction operations by providing information on the real-time location of clustered data or its absence.
  • Allowing a cache to send work to the appropriate node by providing the location of data that requires processing.
  • Providing insight into the effectiveness of data partitioning techniques by verifying the distribution of clustered data.

For more information on data structures, see the Terracotta DSO Data Structures Guide.

Usage

Classes that are injected with cluster awareness can call data locality methods.

The following code example shows the cluster-aware class ClusterAwareClass with a member, localityAwareFoo(), that calls the data locality method getNodesWithObjects():

Code Block

import com.tc.cluster.DsoCluster;
import com.tc.cluster.DsoClusterListener;
import com.tc.injection.annotations.InjectedDsoInstance; 

public class ClusterAwareClass implements DsoClusterListener { 
  @InjectedDsoInstance 
  private DsoCluster cluster; 
 // ...
public void localityAwareFoo(final Collection<Object> myObjects) { 
    cluster.getNodesWithObjects(myObjects); 
  } 
}
{code} See [Terracotta DSO Cluster Events|Cluster Events] for more information on injecting cluster awareness into application classes. h2. The Methods The data-locality methods available are: {toc:minLevel=4|maxLevel=4} Note the following characteristics for these methods: * None returns {{null}}, making null checks unnecessary. In cases where there is no data to return, an empty Set or Map of empty Sets is returned (depending on the method's return type). * An UnclusteredObjectException is thrown if any of the objects or a Map passed to one of these methods is [not clustered|Concept and Architecture Guide#Clustered Objects]. * The "nodes" targeted by these methods refer to Terracotta nodes (application nodes with Terracotta running). Terracotta server instances are not subject data-locality checks. * The values in the Sets or Maps of Sets returned by these methods are DsoNode instances. Each DsoNode instance is uniquely associated with a node and can identify that node by node ID, IP address, and hostname. h4. getNodesWithObject(Object object) Use {{getNodesWithObject(Object object)}} to find which nodes contain the specified object in memory. This method has the following format: {code}

See Terracotta DSO Cluster Events for more information on injecting cluster awareness into application classes.

The Methods

The data-locality methods available are:

Table of Contents
minLevel4
maxLevel4

Note the following characteristics for these methods:

  • None returns null, making null checks unnecessary. In cases where there is no data to return, an empty Set or Map of empty Sets is returned (depending on the method's return type).
  • An UnclusteredObjectException is thrown if any of the objects or a Map passed to one of these methods is not clustered.
  • The "nodes" targeted by these methods refer to Terracotta nodes (application nodes with Terracotta running). Terracotta server instances are not subject data-locality checks.
  • The values in the Sets or Maps of Sets returned by these methods are DsoNode instances. Each DsoNode instance is uniquely associated with a node and can identify that node by node ID, IP address, and hostname.

getNodesWithObject(Object object)

Use getNodesWithObject(Object object) to find which nodes contain the specified object in memory. This method has the following format:

Code Block

java.util.Set<com.tcclient.cluster.DsoNode> 
    getNodesWithObject(java.lang.Object object) throws UnclusteredObjectException
{code}

For

example,

{{

getNodesWithObject(myObject)

}}

returns

a

Set

containing

the

nodes

which

have

myObject

in

memory.

If

myObject

is

not

resident

in

any

node's

memory,

an

empty

Set

is

returned.

If

myObject

is

not

clustered,

an

UnclusteredObjectException

is

thrown.

h4.

getNodesWithObjects(Object

objects

...

)

Use

{{

getNodesWithObjects(Object

objects

...

)

}}

to

find

which

nodes

contain

the

specified

objects

in

memory.

This

method

has

the

following

format:

{

Code Block
}

java.util.Map<?,java.util.Set<com.tcclient.cluster.DsoNode>> 
    getNodesWithObjects(java.lang.Object... objects) throws UnclusteredObjectException
{code}

For

example,

{{

getNodesWithObject(myObject1,

myObject2,

myObject3)

}}

returns

a

Map

with

each

key

being

one

of

the

specified

objects

(myObject1,

myObject2,

or

myObject3)

and

each

value

being

a

Set

of

nodes

which

have

that

object

in

memory.

If

an

object

is

not

resident

in

any

node's

memory,

its

corresponding

value

is

an

empty

Set.

If

any

of

the

objects

specified

is

not

clustered,

an

UnclusteredObjectException

is

thrown.

h4.

getNodesWithObjects(Collection

objects)

Use

{{

getNodesWithObjects(Collection

objects)

}}

to

find

which

nodes

contain

the

objects

from

the

specified

Collection

in

memory.

This

method

has

the

following

format:

{

Code Block
}

java.util.Map<?,java.util.Set<com.tcclient.cluster.DsoNode>> 
    getNodesWithObjects(java.util.Collection<?> objects) throws UnclusteredObjectException
{code}

For

example,

{{

getNodesWithObjects(myObjects)

}}

returns

a

Map

with

each

key

being

an

object

from

the

Collection

myObjects

and

each

value

being

a

Set

of

nodes

which

have

that

object

in

memory.

If

an

object

is

not

resident

in

any

node's

memory,

its

corresponding

value

is

an

empty

Set.

If

any

of

the

objects

in

myObjects

is

not

clustered,

an

UnclusteredObjectException

is

thrown.

h4.

getKeysForOrphanedValues(Map

map)

Use

{{

getKeysForOrphanedValues(Map

map)

}}

to

generate

a

Set

of

keys

for

Map

values

(objects)

that

are

not

resident

in

the

memory

of

any

nodes.

The

map

passed

to

{{

getKeysForOrphanedValues(Map

map)

}}

must

be

clustered

and

support

partial

loading.

This

method

has

the

following

format:

{

Code Block
}

<K> java.util.Set<K> getKeysForOrphanedValues(java.util.Map<K,?> map) throws UnclusteredObjectException
{code}

For

example,

{{

getKeysForOrphanedValues(myMap)

}}

returns

a

Set

of

keys

from

myMap

for

any

objects

not

found

in

memory

on

any

node.

If

myMap

is

not

clustered,

an

UnclusteredObjectException

is

thrown.

h4.

getKeysForLocalValues(Map

map)

Use

{{

getKeysForLocalValues(Map

map)

}}

to

generate

a

Set

of

keys

for

Map

values

(objects)

that

are

resident

in

the

memory

of

the

local

node.

The

map

passed

to

{{

getKeysForLocalValues(Map

map)

}}

must

be

clustered

and

support

partial

loading.

This

method

has

the

following

format:

{

Code Block
}

<K> java.util.Set<K> getKeysForLocalValues(java.util.Map<K,?> map) throws UnclusteredObjectException
{code}

For

example,

{{

getKeysForLocalValues(myMap)

}}

returns

a

Set

of

keys

from

myMap

for

any

objects

found

in

the

memory

of

the

local

node.

If

no

objects

from

myMap

are

found,

an

empty

Set

is

returned.

If

myMap

is

not

clustered,

an

UnclusteredObjectException

is

thrown.

{div9}