WriteRetentionStore (n-orm core 0.0.1-SNAPSHOT API)

java.lang.Object
- com.googlecode.n_orm.storeapi.DelegatingStore
- - com.googlecode.n_orm.cache.write.WriteRetentionStore

All Implemented Interfaces:

Store
```
public class WriteRetentionStore
extends DelegatingStore
```
A DelegatingStore that retains all writes (#storeChanges(MetaInformation, String, String, ColumnFamilyData, Map, Map) and delete(MetaInformation, String, String), that is PersistingElement.store() and PersistingElement.delete()) during a certain amount of time. This kind of store is obviously thread safe, and interesting in case rows are often updated by dramatically lowering the number of write requests on the actual store.
Writes are actually issued to the actual store after a given time. If other writes for the same persisting element occur during this period, they are merged with retained write for this persisting element and eventually sent. As an example, if a persisting element is stored at time t1, changed and stored again at time t2 such that t2-t1 is less than the retention time, only one store request is issued to the actual store, after t1+retention time.

Reads (as DelegatingStore.get(MetaInformation, String, String, Set), PersistingElement.activate(String...)) do not explore data "retended" here. As a example, activating, changing, storing, and then activating again a persisting element using this kind of store can re-activate it as it was before the change. Same remark holds for testing an element of existence, counting element, or getting a list of elements that match criteria.

This store can be deactivated ; in the latter case, it merely acts as a delegating store with no delay. To en/de-activate, use setEnabledByDefault(boolean). A thread can anyway be authorized to activate for itself (and only itself) any de-activated write retention store if calling before setEnabledForCurrentThread(boolean).

This store can be supervised using getPendingRequests(). To grab more metrics (such as the number of requests {getRequestsIn() in}, out, time between a request should be sent and is sent...), you need to enable setCapureHitRatio(boolean) to true, which is not the case by default as it introduces some overhead. It is possible to enable and then disable addtional capture on a regular basis to get metrics samples. In this latter case, older metrics can be reseted.

This store can be activated using the @Persisting annotation on a class or by setting the with-write-retention property on the storage.properties file.

Field Summary

Fields
Modifier and Type Field and Description

static Logger logger

Fields
Modifier and Type	Field and Description
`static Logger`	`logger`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`delete(MetaInformation meta, String table, String id)` Deletes a particular element.
`boolean`	`equals(Object obj)`
`boolean`	`flush(String table, String identifier)` Sends immediately planned requests for the given element.
`static int`	`getActiveSenderThreads()` The approximate number of sending threads.
`static long`	`getAverageLatencyMs()` The average latency (ms) between time at which a request should have been sent and the time it is actually sent
`static long`	`getCumulativeLatencyMs()` The cumulative latency (ms) between time at which a request should have been sent and the time it is actually sent
`static double`	`getHitRatio()` The hit ratio (requests asked / requests (to be)sent ; `isCapureHitRatio()` should be on to capture this metric
`static long`	`getLatencySamples()` Number of latencies accumulated by `getCumulativeLatencyMs()`
`static int`	`getMaxSenderThreads()` Maximum global number of threads used for sending requests to store ; default is 40.
`static int`	`getPendingRequests()` The approximate number of pending write requests.
`static long`	`getRequestsIn()` Number of requests asked ; `isCapureHitRatio()` should be on to capture this metric
`static long`	`getRequestsOut()` Number of requests sent ; `isCapureHitRatio()` should be on to capture this metric
`long`	`getWriteRetentionMs()` Minimum time in ms during which and update (i.e. a `store` or a `delete`) are retained before being sent to the `actual store`.
`static WriteRetentionStore`	`getWriteRetentionStore(long writeRetentionMs, Store s)` Returns a `WriteRetentionStore` with s as `delegate` ; in case s is already a `WriteRetentionStore` with a different `getWriteRetentionMs()`, returns another `WriteRetentionStore` with same `delegate` as s.
`int`	`hashCode()`
`static boolean`	`isCapureHitRatio()` Whether hit ratio metrics should be captured
`boolean`	`isEnabledByDefault()` Whether write retention is enabled by default for thread that did not call `setEnabledForCurrentThread(boolean)`.
`static boolean`	`isEnabledForCurrentThread()` Whether write retention should be enabled for this thread even for `de-activated` write-retention stores.
`static void`	`resetCapureHitRatioMetrics()` Resets any hit-ratio-related metrics `getHitRatio()`, `getRequestsIn()`, `getRequestsOut()`, and `getAverageLatencyMs()`
`static void`	`setCapureHitRatio(boolean captureHitRatio)` Whether hit ratio metrics should be captured
`void`	`setEnabledByDefault(boolean enabled)` Whether write retention is enabled by default for thread that did not call `setEnabledForCurrentThread(boolean)`.
`static void`	`setEnabledForCurrentThread(boolean enabled)` Whether write retention should be enabled for this thread even for `de-activated` write-retention stores.
`static void`	`setMaxSenderThreads(int maxSenderThreads)` Maximum global number of threads used for sending requests to store
`void`	`start()` Called once the store is created ; only one store is instanciated with the same properties.
`void`	`storeChanges(MetaInformation meta, String table, String id, Row.ColumnFamilyData changed, Map<String,Set<String>> removed, Map<String,Map<String,Number>> increments)` Stores given piece of information.

Methods inherited from class com.googlecode.n_orm.storeapi.DelegatingStore
count, exists, exists, get, get, get, get, get, getActualStore, getActualStore, getDeepActualStore, hasTable

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - logger
```
public static final Logger logger
```
- Method Detail
  - getWriteRetentionStore
```
public static WriteRetentionStore getWriteRetentionStore(long writeRetentionMs,
                                                         Store s)
```
    Returns a WriteRetentionStore with s as delegate ; in case s is already a WriteRetentionStore with a different getWriteRetentionMs(), returns another WriteRetentionStore with same delegate as s.
    
    Parameters:
    
    writeRetentionMs - time during which updates are retended to delegate store
    
    s - the actual store, or a WriteRetentionStore with delegating to the actual store
    
    Throws:
    
    IllegalArgumentException - if s is a delegation chain that already contains a WriteRetentionStore
  - isEnabledForCurrentThread
```
public static boolean isEnabledForCurrentThread()
```
    Whether write retention should be enabled for this thread even for de-activated write-retention stores.
  - setEnabledForCurrentThread
```
public static void setEnabledForCurrentThread(boolean enabled)
```
    Whether write retention should be enabled for this thread even for de-activated write-retention stores.
  - getMaxSenderThreads
```
public static int getMaxSenderThreads()
```
    Maximum global number of threads used for sending requests to store ; default is 40.
  - setMaxSenderThreads
```
public static void setMaxSenderThreads(int maxSenderThreads)
```
    Maximum global number of threads used for sending requests to store
  - getActiveSenderThreads
```
public static int getActiveSenderThreads()
```
    The approximate number of sending threads. This number can be above getMaxSenderThreads() in case it was recently set to a lower value.
    
    See Also:
    
    ThreadPoolExecutor.getActiveCount()
  - getPendingRequests
```
public static int getPendingRequests()
```
    The approximate number of pending write requests.
  - isCapureHitRatio
```
public static boolean isCapureHitRatio()
```
    Whether hit ratio metrics should be captured
  - setCapureHitRatio
```
public static void setCapureHitRatio(boolean captureHitRatio)
```
    Whether hit ratio metrics should be captured
  - resetCapureHitRatioMetrics
```
public static void resetCapureHitRatioMetrics()
```
    Resets any hit-ratio-related metrics getHitRatio(), getRequestsIn(), getRequestsOut(), and getAverageLatencyMs()
  - getRequestsIn
```
public static long getRequestsIn()
```
    Number of requests asked ; isCapureHitRatio() should be on to capture this metric
  - getRequestsOut
```
public static long getRequestsOut()
```
    Number of requests sent ; isCapureHitRatio() should be on to capture this metric
  - getHitRatio
```
public static double getHitRatio()
```
    The hit ratio (requests asked / requests (to be)sent ; isCapureHitRatio() should be on to capture this metric
  - getCumulativeLatencyMs
```
public static long getCumulativeLatencyMs()
```
    The cumulative latency (ms) between time at which a request should have been sent and the time it is actually sent
  - getLatencySamples
```
public static long getLatencySamples()
```
    Number of latencies accumulated by getCumulativeLatencyMs()
  - getAverageLatencyMs
```
public static long getAverageLatencyMs()
```
    The average latency (ms) between time at which a request should have been sent and the time it is actually sent
  - getWriteRetentionMs
```
public long getWriteRetentionMs()
```
    Minimum time in ms during which and update (i.e. a store or a delete) are retained before being sent to the actual store. During this time, updates are merged to dramatically reduce number of updates on a same row.
  - isEnabledByDefault
```
public boolean isEnabledByDefault()
```
    Whether write retention is enabled by default for thread that did not call setEnabledForCurrentThread(boolean).
  - setEnabledByDefault
```
public void setEnabledByDefault(boolean enabled)
```
    Whether write retention is enabled by default for thread that did not call setEnabledForCurrentThread(boolean).
  - start
```
public void start()
           throws DatabaseNotReachedException
```
    Description copied from interface: Store
    
    Called once the store is created ; only one store is instanciated with the same properties.
    
    Specified by:
    
    start in interface Store
    
    Overrides:
    
    start in class DelegatingStore
    
    Throws:
    
    DatabaseNotReachedException
  - flush
```
public boolean flush(String table,
                     String identifier)
```
    Sends immediately planned requests for the given element.
    
    Parameters:
    
    table - the table of the element
    
    identifier - the identifier of the element
    
    Returns:
    
    whether some requests were found regarding this element
  - delete
```
public void delete(MetaInformation meta,
                   String table,
                   String id)
            throws DatabaseNotReachedException
```
    Description copied from interface: Store
    
    Deletes a particular element.
    
    Specified by:
    
    delete in interface Store
    
    Overrides:
    
    delete in class DelegatingStore
    
    Throws:
    
    DatabaseNotReachedException
  - storeChanges
```
public void storeChanges(MetaInformation meta,
                         String table,
                         String id,
                         Row.ColumnFamilyData changed,
                         Map<String,Set<String>> removed,
                         Map<String,Map<String,Number>> increments)
                  throws DatabaseNotReachedException
```
    Description copied from interface: Store
    
    Stores given piece of information. In case an element is missing in the data store (table, row, family, ...), it is created.
    
    Specified by:
    
    storeChanges in interface Store
    
    Overrides:
    
    storeChanges in class DelegatingStore
    
    Throws:
    
    DatabaseNotReachedException
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object

Class WriteRetentionStore

Field Summary

Method Summary

Methods inherited from class com.googlecode.n_orm.storeapi.DelegatingStore

Methods inherited from class java.lang.Object

Field Detail

logger

Method Detail

getWriteRetentionStore

isEnabledForCurrentThread

setEnabledForCurrentThread

getMaxSenderThreads

setMaxSenderThreads

getActiveSenderThreads

getPendingRequests

isCapureHitRatio

setCapureHitRatio

resetCapureHitRatioMetrics

getRequestsIn

getRequestsOut

getHitRatio

getCumulativeLatencyMs

getLatencySamples

getAverageLatencyMs

getWriteRetentionMs

isEnabledByDefault

setEnabledByDefault

start

flush

delete

storeChanges

hashCode

equals