Get More Refcardz! Visit refcardz.
com
#127
CONTENTS INCLUDE:
n
Whats New in JPA 2.0
JDBC
Properties
iPad
Access Mode
Mappings
Shared Cache
Additional API and more...
Getting Started with
JPA 2.0
By Mike Keith
The Enterprise Q&A Platform
Collect, Manage and
Share All the Answers
Your Team Needs
> Q&A Software for Enterprise Knowledge Sharing
> Mobile-friendly Responsive Design
> Easy to Customize with Themes and Plugins
Getting Started with JPA 2.0
> Integrates with Your SSO and IT Infrastructure
> Choose Cloud-based or On-premise Hosting
DZone, Inc.
[Link]
Couchbase API: Ultra -fast, Open Source NoSQL Data Access from Java, Ruby & .NET
Get More Refcardz! Visit [Link]
#176
Couchbase API:
CONTENTS INCLUDE:
Connection Management
Ultra-Fast, Open Source NoSQL Data Access
from Java, Ruby, and .NET
Store Operations
Connecting to Couchbase
Writing and Updating Data
Getting stats from Couchbase
By: Don Pinto
Querying data... and More!
Couchbase Server is an open-source NoSQL document database
that provides a flexible data model, easy scalability, consistent highperformance and always-on characteristics. This Refcard covers the APIs
in Java, C#.Net and Ruby used to develop applications using Couchbase
Server 2.0.
Set Operations (Durability requirements)
The set method stores a value to the database with a specified key.
[Link](key, expiry, value [, persistTo] ,[ replicateTo])
[Link](key, expiry, value, transcoder)
JAVA
CONNECTION MANAGEMENT
Parameters:
Connecting to Couchbase Server
string key
Key used to reference the value.
int expiry
Expiry time for the key in seconds. Values
larger than 30*24*60*60 seconds (30 days) are
interpreted as absolute times (from the epoch)
Object value
Value to be stored
enum persistTo
The amount of nodes the item should be
persisted to before returning. - MASTER/ONE,
TWO, THREE or FOUR nodes
enum replicateTo
The amount of nodes the item should be
replicated to before returning ZERO, ONE, TWO or
THREE nodes
Transcoder<T>
transcoder
Transcoder class to be used to serialize values
private static CouchbaseClient client;
new CouchbaseClient(urls, bucket, password)
Parameters:
string urls
Linked list containing one or more URLs as strings
String username
Username for Couchbase bucket
String password
Password for Couchbase bucket
Disconnecting from Couchbase Server
[Link]();
[Link](long TimeValue, TimeUnit);
RETRIEVE OPERATIONS
Parameters:
long TimeValue
Wait value until any outstanding queued work is
completed
enum TimeUnit
[Link], [Link]
There are several different flavors of retrieve operations in the Couchbase
Server 1.1 Java SDK
[Link](key)
[Link](key, transcoder)
[Link](key, expiry)
[Link](key, expiry, transcoder)
[Link](key, expiry)
[Link](key, expiry, transcoder)
[Link](keycollection)
[Link](keyn)
[Link](transcoder, keyn)
[Link](keycollection, transcoder)
[Link](key, transcoder)
[Link](key)
----Snippet contd on next page--->
STORE OPERATIONS
Key
Keys can be any UTF-8 string up to 250 characters long. Metadata for keys
is 125 bytes + length of key and always kept in RAM.
Value
If Value is a Hash, it is converted to JSON for Documents and decoded
back to a Hash on Retrieve. Value can also be Strings, Binary Strings,
Integers (for Atomic Counters, must be positive Integer), and Decimal.
If Value is a JSON String you will get back a JSON String (like any other
string) that is not parsed by JSON decoder into a Hash.
Add Operations
The add method adds a value to the database with the specified key, but
will fail if the key already exists in the database.
[Link](key, expiry, value [, persistTo] ,[ replicateTo] )
[Link](key, expiry, value, transcoder)
Replace Operations
The replace method will replace an existing key with a new value but will
fail if the key does not exist in the database.
[Link](key, expiry, value [, persistTo] ,[ replicateTo])
[Link](key, expiry, value, transcoder)
DZone, Inc.
[Link]
Couchbase API
[Link](key, expiry)
[Link](key, expiry, transcoder)
[Link](keycollection)
[Link](keyn)
[Link](transcoder, keyn)
[Link](keycollection, transcoder)
[Link](key, transcoder)
[Link](key [,getl-expiry])
[Link](key [,getl-expiry], transcoder)
[Link](key, getl-expiry)
[Link](key, getl-expiry, transcoder)
[Link](key)
[Link](key, transcoder)
[Link](key)
[Link](key, transcoder)
[Link](key, casunique)
Parameters:
String key
Expiry time for the key in seconds. Values
larger than 30*24*60*60 seconds (30
days) are interpreted as absolute times
(from the epoch)
Collection<String> keycollection
One or more keys used to reference a
value
String keyn
One or more keys used to reference a
value
long casunique
Unique value used to identify a key/value
combination
int getl-expiry
Expiry time in seconds for lock :
Default 15, Maximum 30
Transcoder<T> transcoder
Transcoder class to be used to serialize
values
Expiry time for the key in seconds. Values
larger than 30*24*60*60 seconds (30 days) are
interpreted as absolute times (from the epoch)
Object value
Value to be stored
enum persistTo
The amount of nodes the item should be persisted
to before returning. - MASTER/ONE, TWO, THREE
or FOUR nodes
enum replicateTo
The amount of nodes the item should be replicated
to before returning ZERO, ONE, TWO or THREE
nodes
Transcoder<T>
transcoder
Transcoder class to be used to serialize values
QUERY OPERATIONS
Key used to reference the value. The key
cannot contain control characters or
whitespace
int expiry
int expiry
With Couchbase Server 2.0, you can add the power of views and querying
those views to your applications.
Create a view object to be used when querying a view :
[Link](ddocname, viewname)
Parameters:
String ddocname
Design document name
String viewname
View name within a design document
Then create a new query object to be used when querying the view:
[Link]()
Query query = new Query();
Once the view and query objects are available, the results of the server view
can be accessed using:
For more information on creating design documents using Java or for
cluster management operations, take a look at [Link]
com/develop/java/current
[Link](view, query)
UPDATE OPERATIONS
Parameters:
The update methods support different methods of updating and changing
existing information within Couchbase Server.
View view
View object associated with a server view
Query query
Query object associated with a server view
Before accessing the view, a list of options can be set with the query object:
[Link](casunique, key, value)
[Link](casunique, key, value, transcoder)
[Link](key, casunique, value)
[Link](key, casunique, expiry, value, transcoder)
[Link](key, casunique, value, transcoder)
[Link](key, casunique, value [, persistTo] ,[ replicateTo])
[Link](key, casunique, expiry, value, transcoder)
[Link](key, casunique, value, transcoder)
[Link](key, offset)
[Link](key, offset)
[Link](key, offset, default)
[Link](key, offset, default, expiry)
[Link](key [, persistTo] ,[ replicateTo])
[Link](key, offset)
[Link](key, offset)
[Link](key, offset, default)
[Link](key, offset, default, expiry)
[Link](casunique, key, value)
[Link](casunique, key, value, transcoder)
[Link](key, expiry)
[Link](String key) to set the key to query in the view
[Link](ComplexKey key) to set the key to query in the view
[Link](String startKey) to set the starting key
[Link](ComplexKey startKey) to set the starting key
[Link](String endKey) to set the ending key
[Link](ComplexKey endKey) to set the ending key
[Link](String startKey, String endKey) to set a range
[Link](ComplexKey startKey, ComplexKey endKey)
[Link](boolean descending) to sort in descending order
[Link](boolean include) to include the JSON doc
[Link](boolean reduce) execute the reduce function
[Link](Stale reduce) set to OK will not refresh the view even if it
is stale, set to UPDATE_AFTER will update the view after the stale result is
returned, FALSE will update the view and return the latest results.
The format of the returned information of the query method is:
ViewResponse or any of the other inherited objects such as
ViewResponseWithDocs, ViewResponseNoDocs, ViewResponseReduced.
Parameters:
long casunique
Unique value used to identify a key/value
combination
String key
Key used to reference the value. The key cannot
contain control characters or whitespace
int offset
Integer offset value to increment / decrement
(default is 1)
int default
Default value to increment/decrement if key does
not exist
DZone, Inc.
The ViewResponse method provides an iterator() method for iterating
through the rows as a ViewRow interface. The ViewResponse method also
provides a getMap() method where the result is available as a map.
RUBY
CONNECTING TO COUCHBASE
client = [Link](url, options = {});
client = [Link](options = {});
[Link]
Couchbase API
Hash Parameters:
Simple Get Operations
:hostname
IP address for Couchbase Node (String)
:bucket
Bucket name (String) [optional, default is default]
:password
SASL password for Bucket (String) [optional]
:nodelist
Array of IPs for Couchbase Nodes ([String]) like
[[Link]:8091, [Link]]
val = [Link](key, options = {})
val = client[key]
Extended Tuple Get Operations
val, flags, cas = [Link](key, :extended => true)
val, flags, cas = client[key, :extended => true]
client = [Link]
There is a shared single instance of the Couchbase connection object in the
Couchbase-model gem and can be used once connected, or when settings
are specified in /config/[Link], which connects on Rails startup.
Multi-Get Operations
val_array = [Link](keys)
val_hash = [Link](keys, :assemble_hash => true)
WRITING AND UPDATING DATA
options:
Add Operations
The add method adds a value to the database with the specified key,
but will fail (Couchbase::Error::KeyExists) if the key already exists in the
database.
[Link](key, value, options = {})
[Link][key, options = {}] = value
Replace Operations
:extended
[String, Symbol] Key used to reference the value
:quiet
[true, false] Return nil for missing keys default, or false to
Return Couchbase::Error::KeyNotFound for missing key
:ttl
[Fixnum, Integer] Get and Touch, :ttl will also reset the
TTL at the same time as the get (seconds)
:lock
Lock the document, true to use default lock timeout, or
integer for number of seconds to lock
:format
[:document, :plain, :marshal] Explicit format setting, :plain
for strings, :document for Hash(JSON), :marshal to use
[Link] and [Link]
:assemble_hash
[true, false] For Multi-Get, will return a Hash keyed on the
document keys instead of default of array
The replace method will replace an existing key with a new value but will fail
(Couchbase::Error::NotFound) if the key does not exist in the database.
[Link](key, value, options = {})
[Link][key, options = {}] = value
GETTING STATS FROM COUCHBASE
Set Operations
The set method stores a value to the database with a specified key,
overwriting existing content if it exists (see add/replace above).
Obtain stats from all servers for the connection (bucket)
[Link]
[Link][stats]
[Link](key, value, options = {})
[Link][key, options = {}] = value
To fetch memory stats
options:
:ttl
[Fixnum, Integer] Time to Live in seconds [optional]
:flags
[Fixnum] Flags that you want to store/retrieve [optional]
:cas
[Fixnum] Optimistic locking for update control, must match
the document cas in Couchbase to succeed
:format
[:document, :plain, :marshal] Explicit format setting, :plain for
strings, :document for Hash(JSON), :marshal to use Marshal.
load and [Link]; format is :document by default
[Link](:memory)
Parameters:
stat
DELETING AND UPDATING DATA
Asynchronous Store Example (Block)
[Link] do
[Link](foo
[Link]
[Link]?
[Link]
[Link]
[Link]
end
end
Individual stat string (i.e. "curr_items")
To delete keys/values
=> val1, bar => val2) do |ret|
#=> :add
#=> true
#=> foo, bar in separate calls
[Link](key)
Atomic Counter Operations
Atomic Counters are only atomic per cluster, but are useful for many
different patterns and numeric data. They are unsigned positive integers.
You cannot use atomic operations on floats or objects or arrays.
READING DATA
[Link](key, delta, options = {})
[Link](key, delta, options = {})
The Get method is versatile, allowing for both optimistic and pessimistic
locking, multiple gets, and hash-like syntax.
DZone, Inc.
[Link]
Couchbase API
options:
:startkey_docid
[String] Document id to start with (to allow pagination
for duplicate startkeys
[true, false] If set to true, if key doesnt exist, initializes to zero
but doesnt increment, can be combined with :initial
:endkey_docid
[String] Last document id to include in the output (to
allow pagination for duplicate startkeys)
:initial
[Fixnum, Unsigned Integer] Sets initial value if key doesnt exist,
doesnt increment the initial value!
:inclusive_end
[true, false] If true, specificed end key is included in
result
:extended
[true, false] Returns [value, cas] tuple instead of just value
:limit
[Fixnum] Limit the results returned
[Fixnum, Integer] Sets TTL, doesnt alter existing TTL, will only
be applied to a new item created via :create and/or :initial
:skip
[Fixnum] Skip a number of results before returning
(can be used with :limit to page through results)
:reduce
[true, false] Perform the reduce function defined in the
view. If there is no reduce defined default is false and
setting to true will return error.
:group
[true, false] Groups results using the view defined
reduce function
:group_level
[Fixnum] Sets the grouping level for compound keys
:stale
[:false, :update_after, :ok] Consistency setting, :false
initiates Design Document to update indexes before
returning results, :update_after updates indexes after
returning results, :ok doesnt trigger indexers and
returns existing indexed results
:body
[Hash] Takes same parameters as options but does
it as a POST if the query has many parameters or is
complex
:on_error
[:continue, :stop] Behavior setting if an error occurs
during view query
delta
[Fixnum] Amount to incr/decr, default is 1, can be up to 64 bits
:create
:ttl
Touch Operations
Reset the TTL expiration on one or more keys explicitly with the touch
command, can also be done with a get command.
[Link](key, ttl)
[Link]({key1=> ttl1, key2 => ttl2})
Durability Requirements
Observe the state of the keys on all the nodes or using :replicated and
:persisted it allows to set up the waiting rule.
[Link](*keys, options = {})
client.observe_and_wait(*keys, options = {})
Non-JSON Operations
For non-json values, prepend and append can concatenate to existing
values accordingly. Defaults to:plain format for encoder/decoder.
.NET
[Link](key, value)
[Link](key, value)
CONNECTING TO COUCHBASE
var config = new CouchbaseClientConfiguration();
[Link](new Uri([Link]
[Link] = <bucketname>;
var client = new CouchbaseClient(config);
QUERYING DATA
With Couchbase Server 2.0, you can create Indexes through Map/Reduce
functions. [Link]
[Link]
WRITING DATA
Based on the storemode, Store and ExecuteStore may be an Add, Replace
or Set operation. Execute APIs return the operation result.
Create Design Doc Object
Refer to the design_doc by name, the Views are an array of view names, as
well as functions defined by name.
Store Operations
[Link](storemode, key, value)
[Link](storemode, key, value, validfor)
[Link](storemode, key, value, expiresat)
ddoc = client.design_docs[design_doc_name]
[Link]
#=> [view_name, view_name_2, ]
Use dot notation for accessing the view by your defined view name and
pass in options for query parameters:
ExecuteStore Operations
ddoc.view_name(params = {}).each do |doc|
# do stuff with docs
end
[Link](storemode,
[Link](storemode,
[Link](storemode,
[Link](storemode,
[Link](storemode,
[Link](storemode,
ReplicateTo)
options:
key,
key,
key,
key,
key,
key,
value)
value,
value,
value,
value,
value,
expiresat)
validfor)
ReplicateTo)
PersistTo)
PersistTo,
:include_docs
[true, false] Perform get with key on rows returned
with key (non-reduce)
:descending
[true, false], reverse order of returned rows
String key
Key used to reference the value.
:key
[String, Fixnum, Hash, Array] Return only rows with
index key that match :key, simple and compound keys
can be used (JSON encoded)
Object value
Value to be stored
StoreMode storemode
[Array] Return only rows that match array of keys
(see :key), both simple and compound keys (JSON
encoded)
Storage mode for a given key/value pair can be
Add, Replace or Set.
Timespan validfor
Expiry timespan (in seconds) for key
DateTime expiresat
Explicit expiry time for key
:startkey
[String, Fixnum, Hash, Array] Range query from :start_
key to :end_key (JSON encoded)
Enum PersistsTo
Persist to one or more replicas. Master plus one,
two, three replicas
:endkey
[String, Fixnum, Hash, Array] Range query from :start_
key to :end_key (JSON encoded)
Enum ReplicateTo
Replicate to zero or more replicas
:keys
DZone, Inc.
Parameters:
[Link]
Couchbase API
READING DATA
Get Operations
[Link](key, expiry)
[Link](key, expiry)
[Link](key)
[Link](keyarray)
[Link](key)
[Link](keyarray)
[Link](key)
Timespan validfor
Expiry timespan (in seconds) for key
DateTime expiresat
Explicit expiry time for key
Object defaultvalue
Value to be stored if the key does not exists
offset
Integer offset value to increment or decrement
(default 1)
casunique
Unique value used to verify a key/value
combination
QUERYING DATA
Parameters:
String key
Key used to reference the value. The key cannot
contain control characters or whitespace
object expiry
Expiry time for the key in seconds. Values
larger than 30*24*60*60 seconds (30 days) are
interpreted as absolute times (from the epoch)
List <string> keyarray
Array of keys used to reference one or more values
With Couchbase Server 2.0, you can add views and query those views
using your applications.
Create a view object to be used when querying a view :
GetView(designName, viewName)
Parameters:
UPDATING DATA
String designName
Design document name
String viewName
View name within a design document
Update existing information on the server:
There is also a generic version of GetView, which has a third boolean
parameter that tells the client to lookup the original document by its ID.
[Link](key, value)
[Link](key, casvalue, value)
[Link](key, value)
[Link](key, casvalue, value)
[Link](storemode, key, value)
[Link](storemode, key, value, casunique)
[Link](storemode, key, value, validfor, casunique)
[Link](storemode, key, value)
[Link](storemode, key, value, casunique)
[Link](storemode, key, value, expiresat, casunique)
[Link](storemode, key, value, validfor, casunique)
[Link](key, defaultvalue, offset)
[Link](key, defaultvalue, offset, casunique)
[Link](key, defaultvalue, offset, expiresat, casunique)
[Link](key, defaultvalue, offset, validfor, casunique)
[Link](key, defaultvalue, offset, expiresat)
[Link](key, defaultvalue, offset, validfor)
[Link](key, defaultvalue, offset)
[Link](key, defaultvalue, offset, casunique)
[Link](key, defaultvalue, offset, validfor, casunique)
[Link](key, defaultvalue, offset, expiresat)
[Link](key, defaultvalue, offset, validfor)
[Link](key, defaultvalue, offset)
[Link](key, defaultvalue, offset, casunique)
[Link](key, defaultvalue, offset, expiresat,
casunique)
[Link](key, defaultvalue, offset, validfor,
casunique)
[Link](key, defaultvalue, offset, expiresat)
[Link](key, defaultvalue, offset, validfor)
[Link](key)
[Link](key)
[Link](key, defaultvalue, offset)
[Link](key, defaultvalue, offset, casunique)
[Link](key, defaultvalue, offset, expiresat,
casunique)
[Link](key, defaultvalue, offset, validfor,
casunique)
[Link](key, defaultvalue, offset, expiresat)
[Link](key, defaultvalue, offset, validfor)
[Link](key, defaultvalue, offset)
[Link](key, defaultvalue, offset, casunique)
[Link](key, defaultvalue, offset, expiresat, casunique)
[Link](key, defaultvalue, offset, validfor, casunique)
[Link](key, defaultvalue, offset, expiresat)
[Link](key, defaultvalue, offset, validfor)
[Link](key, value)
[Link](key, casunique, value)
[Link](key, value)
[Link](key, casunique, value)
[Link](key, expiry)
GetView<T>(designName, viewName, bLookup)
You can iterate over the returned collection as follows:
var beersByNameAndABV = [Link]<Beer>(beers, by_name_
and_abv);
foreach(var beer in beersByNameAndABV) { }
If you iterate over a strongly typed view, each item is of the type you
specified. If you use the non-generic version, each item you enumerate over
will be of type IViewRow. IViewRow provides methods for accessing details
of the row that are not present when using strongly typed views.
To get the original document from Couchbase:
[Link]()
To get a Dictionary representation of the view:
[Link]
To get the original documents ID:
[Link]
To get the key emitted by the map function:
[Link]
To limit the number of documents returned by the query to 10:
GetView(designName, viewName).Limit(10)
To group the results when using _count for example:
Parameters:
GetView(designName, viewName).Group(true)
String key
Key used to reference the value.
Object value
Value to be stored
StoreMode storemode
Storage mode for a given key/value pair
To disallow stale results in the view:
GetView(designName, viewName).Stale([Link])
DZone, Inc.
[Link]
Couchbase API
To limit the number of results to and order the results in descending order:
GetView(designName, viewName).Limit(5).Descending(true)
GETTING STARTED WITH COUCHBASE C# LIBRARIES
Using the NuGet package manager you can get the Couchbase .Net client
using Install-Package CouchbaseNetClient
Finally, add a reference to the Couchbase .Net Client Library in your project.
Enjoy building your application using Couchbase Server!
Useful Links
To create a new MVC project using Couchbase Server, select File -> New
Project and then select Web -> [Link] MVC4 application under the Visual
C# project templates. Give your project a name and click OK to create the
solution.
ABOUT THE AUTHORS
Couchbase Website: [Link]
Couchbase Blog: [Link]
Developer SDKs: [Link]
Download: [Link]
Autodocs: [Link]
Java : [Link]
.NET : [Link]
Ruby : [Link]
RECOMMENDED BOOK
Don Pinto is a Product Marketing Manager at Couchbase
responsible for product marketing development,
positioning, messaging and collateral. For this Refcard,
Don worked with Jasdeep Jaitla, John Zablocki,
Michael Nitschinger, Sergey Avseyev and Tugdual
Grall, all employees of Couchbase, Inc. Check out their
website[[Link] and blog[[Link]
[Link]/] for Couchbase news, tips, and tricks.
Todays highly interactive websites pose a
challenge for traditional SQL databasesthe
ability to scale rapidly and serve loads of
concurrent users. With this concise guide, youll
learn how to build web applications on top of
Couchbase Server 2.0, a NoSQL database that
can handle websites and social media where
hundreds of thousands of users read and write
large volumes of information.
Buy
Here
Browse our collection of over 150 Free Cheat Sheets
Upcoming Refcardz
Free PDF
C++
Sencha Touch
Clean Code
Git for the Enterprise
DZone, Inc.
150 Preston Executive Dr.
Suite 201
Cary, NC 27513
Copyright 2013 DZone, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval
system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior
written permission of the publisher.
888.678.0399
919.678.0300
Refcardz Feedback Welcome
$7.95
DZone communities deliver over 6 million pages each month to
more than 3.3 million software developers, architects and decision
makers. DZone offers something for everyone, including news,
tutorials, cheat sheets, blogs, feature articles, source code and more.
"DZone is a developer's dream", says PC Magazine.
refcardz@[Link]
Sponsorship Opportunities
sales@[Link]
Version 1.0