http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/rest_examples.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/rest_examples.html.md.erb b/geode-docs/rest_apps/rest_examples.html.md.erb deleted file mode 100644 index 3994ff0..0000000 --- a/geode-docs/rest_apps/rest_examples.html.md.erb +++ /dev/null @@ -1,691 +0,0 @@ ---- -title: Sample REST Applications ---- - -<a id="topic_lvp_cd5_m4"></a> - - -This section provides examples that illustrate how multiple clients, both REST and native, can access the same Geode region data. - -**Note:** -You must set PDX read-serialized to true when starting the cache server to achieve interoperability between different clients. See [Setup and Configuration](setup_config.html#topic_e21_qc5_m4) for instructions on starting up REST-enabled cache servers. - -The following examples demonstrate the following: - -1. A Java REST client creates a Person object on key 1. This client references the following supporting examples (also provided): - 1. Geode cache client - 2. REST client utility - 3. Date Time utility - 4. Person class - 5. Gender class - -2. A Ruby REST client also gets data for key 1 and updates it. -3. A Python REST Client demonstrates the creation and modification of objects. - **Note:** - An additional Python REST client reference application is available here: [https://github.com/gemfire/py-gemfire-rest](https://github.com/gemfire/py-gemfire-rest). - -The following Java examples assume a project directory structure similar to the following: - -<img src="../images/rest_example_java_packages.png" id="topic_lvp_cd5_m4__image_rvd_ydd_3r" class="image" /> -## \#1. REST Java Client (RestClientApp.java) - -``` pre -package org.apache.geode.restclient; - - import org.springframework.http.HttpHeaders; - import org.springframework.http.MediaType; - import org.springframework.http.HttpMethod; - import org.springframework.http.HttpEntity; - import org.springframework.http.ResponseEntity; - import org.springframework.web.client.HttpClientErrorException; - import org.springframework.web.client.HttpServerErrorException; - - import org.apache.geode.util.RestClientUtils; - - import java.util.ArrayList; - import java.util.List; - -@SuppressWarnings( "unused") - public class RestClientApp { - private static final String PEOPLE_REGION = "/People"; - - private static final String PERSON1_AS_JSON = "{" - + "\"@type\ ": \"org.apache.geode.domain.Person\ "," + "\"id\ ": 1," - + " \"firstName\ ": \"Jane\ "," + " \"middleName\ ": \"H\ "," - + " \"lastName\ ": \"Doe1\ "," + " \"birthDate\ ": \"04/12/1983\ "," - + "\"gender\ ": \"MALE\ "" + "}"; - - public static void main( final String... args) throws Exception { - doCreate(PEOPLE_REGION, "1"); - System.out.println( "Programme has run successfully...!"); - } - - private static HttpHeaders setAcceptAndContentTypeHeaders(){ - List<MediaType> acceptableMediaTypes = new ArrayList<MediaType>(); - acceptableMediaTypes.add(MediaType.APPLICATION_JSON); - - HttpHeaders headers = new HttpHeaders(); - headers.setAccept(acceptableMediaTypes); - headers.setContentType(MediaType.APPLICATION_JSON); - return headers; - } - - private static void doCreate( final String regionNamePath, final String key) { - HttpHeaders headers = setAcceptAndContentTypeHeaders(); - HttpEntity< String> entity = new HttpEntity< String>(PERSON1_AS_JSON, headers); - try { - ResponseEntity< String> result = RestClientUtils.getRestTemplate().exchange( - "http://localhost:8080/gemfire-api/v1/People?key=1"; , HttpMethod.POST, - entity, String.class); - - System.out.println( "STATUS_CODE = " + result.getStatusCode().value()); - System.out.println( "HAS_BODY = " + result.hasBody()); - System.out.println( "LOCATION_HEADER = " + result.getHeaders().getLocation().toString()); - } catch (HttpClientErrorException e) { - System.out.println( "Http Client encountered error, msg:: " + e.getMessage()); - } catch(HttpServerErrorException se) { - System.out.println( "Server encountered error, msg::" + se.getMessage()); - } catch (Exception e) { - System.out.println( "Unexpected ERROR...!!"); - } - } -} -``` - -## \#1a. Geode Cache Java Client (MyJavaClient.java) - -``` pre -package org.apache.geode.javaclient; - - import java.util.Calendar; - import java.util.HashMap; - import java.util.Map; - - import org.apache.geode.cache.Region; - import org.apache.geode.cache.client.ClientCache; - import org.apache.geode.cache.client.ClientCacheFactory; - import org.apache.geode.cache.client.ClientRegionFactory; - import org.apache.geode.cache.client.ClientRegionShortcut; - import org.apache.geode.domain.Gender; - import org.apache.geode.domain.Person; - import org.apache.geode.pdx.PdxInstance; - import org.apache.geode.util.DateTimeUtils; - - public class MyJavaClient { - - public static void main( String[] args) { - ClientCacheFactory cf = new ClientCacheFactory().addPoolServer( "localhost", 40405); - ClientCache cache = cf.setPdxReadSerialized( true).create(); - ClientRegionFactory rf = cache.createClientRegionFactory(ClientRegionShortcut.PROXY); - - Region region = rf.create( "People"); - - //Get data on key "1" , update it and put it again in cache - Person actualObj = null; - Object obj = region.get( "1"); - if(obj instanceof PdxInstance){ - System.out.println( "Obj is PdxInstance"); - PdxInstance pi = (PdxInstance)obj; - Object obj2 = pi.getObject(); - if(obj2 instanceof Person){ - actualObj = (Person)obj2; - System.out.println( "Received Person :" + actualObj.toString()); - } else { - System.out.println( "Error: obj2 is expected to be of type Person"); - } - } else { - System.out.println( "Error: obj is expected to be of type PdxInstance"); - } - - //update the received object and put it in cache - if(actualObj != null){ - actualObj.setFirstName( "Jane_updated"); - actualObj.setLastName( "Doe_updated"); - region.put( "1", actualObj); - } - - //Add/putAll set of person objects - final Person person2 = new Person(102L, "Sachin", "Ramesh", "Tendulkar", DateTimeUtils.createDate(1975, Calendar.DECEMBER, 14), Gender.MALE); - final Person person3 = new Person(103L, "Saurabh", "Baburav", "Ganguly", DateTimeUtils.createDate(1972, Calendar.AUGUST, 29), Gender.MALE); - final Person person4 = new Person(104L, "Rahul", "subrymanyam", "Dravid", DateTimeUtils.createDate(1979, Calendar.MARCH, 17), Gender.MALE); - final Person person5 = new Person(105L, "Jhulan", "Chidambaram", "Goswami", DateTimeUtils.createDate(1983, Calendar.NOVEMBER, 25), Gender.FEMALE); - final Person person6 = new Person(101L, "Rahul", "Rajiv", "Gndhi", DateTimeUtils.createDate(1970, Calendar.MAY, 14), Gender.MALE); - final Person person7 = new Person(102L, "Narendra", "Damodar", "Modi", DateTimeUtils.createDate(1945, Calendar.DECEMBER, 24), Gender.MALE); - final Person person8 = new Person(103L, "Atal", "Bihari", "Vajpayee", DateTimeUtils.createDate(1920, Calendar.AUGUST, 9), Gender.MALE); - final Person person9 = new Person(104L, "Soniya", "Rajiv", "Gandhi", DateTimeUtils.createDate(1929, Calendar.MARCH, 27), Gender.FEMALE); - final Person person10 = new Person(104L, "Priyanka", "Robert", "Gandhi", DateTimeUtils.createDate(1973, Calendar.APRIL, 15), Gender.FEMALE); - final Person person11 = new Person(104L, "Murali", "Manohar", "Joshi", DateTimeUtils.createDate(1923, Calendar.APRIL, 25), Gender.MALE); - final Person person12 = new Person(104L, "Lalkrishna", "Parmhansh", "Advani", DateTimeUtils.createDate(1910, Calendar.JANUARY, 01), Gender.MALE); - final Person person13 = new Person(104L, "Shushma", "kumari", "Swaraj", DateTimeUtils.createDate(1943, Calendar.AUGUST, 10), Gender.FEMALE); - final Person person14 = new Person(104L, "Arun", "raman", "jetly", DateTimeUtils.createDate(1942, Calendar.OCTOBER, 27), Gender.MALE); - final Person person15 = new Person(104L, "Amit", "kumar", "shah", DateTimeUtils.createDate(1958, Calendar.DECEMBER, 21), Gender.MALE); - final Person person16 = new Person(104L, "Shila", "kumari", "Dixit", DateTimeUtils.createDate(1927, Calendar.FEBRUARY, 15), Gender.FEMALE); - - Map< String, Object> userMap = new HashMap< String, Object>(); - userMap.put( "2", person6); - userMap.put( "3", person6); - userMap.put( "4", person6); - userMap.put( "5", person6); - userMap.put( "6", person6); - userMap.put( "7", person7); - userMap.put( "8", person8); - userMap.put( "9", person9); - userMap.put( "10", person10); - userMap.put( "11", person11); - userMap.put( "12", person12); - userMap.put( "13", person13); - userMap.put( "14", person14); - userMap.put( "15", person15); - userMap.put( "16", person16); - - //putAll all person - region.putAll(userMap); - - System.out.println( "successfully Put set of Person objects into the cache"); - } - -} -``` - -## \#1b. REST Client Utilities (RestClientUtils.java) - -``` pre -package org.apache.geode.util; - - - import java.net.URI; - import java.text.SimpleDateFormat; - import java.util.ArrayList; - import java.util.List; - import org.springframework.http.converter.ByteArrayHttpMessageConverter; - import org.springframework.http.converter.HttpMessageConverter; - //import org.springframework.http.converter.ResourceHttpMessageConverter; - import org.springframework.http.converter.StringHttpMessageConverter; - import org.springframework.http.converter.json.Jackson2ObjectMapperFactoryBean; - import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter; - import org.springframework.web.client.RestTemplate; - import org.springframework.web.util.UriComponentsBuilder; - - public class RestClientUtils { - - public static final String BASE_URL = "http://192.0.2.0:8080"; ; - public static final String GEMFIRE_REST_API_CONTEXT = "/gemfire-api"; - public static final String GEMFIRE_REST_API_VERSION = "/v1"; - public static final URI GEMFIRE_REST_API_WEB_SERVICE_URL = URI - .create(BASE_URL + GEMFIRE_REST_API_CONTEXT + GEMFIRE_REST_API_VERSION); - - public static RestTemplate restTemplate; - public static RestTemplate getRestTemplate() { - if (restTemplate == null) { - restTemplate = new RestTemplate(); - final List<HttpMessageConverter<?>> messageConverters = new ArrayList<HttpMessageConverter<?>>(); - - messageConverters.add( new ByteArrayHttpMessageConverter()); - //messageConverters.add(new ResourceHttpMessageConverter()); - messageConverters.add( new StringHttpMessageConverter()); - messageConverters.add(createMappingJackson2HttpMessageConverter()); - // messageConverters.add(createMarshallingHttpMessageConverter()); - - restTemplate.setMessageConverters(messageConverters); - } - return restTemplate; - } - - public static HttpMessageConverter< Object> createMappingJackson2HttpMessageConverter() { - final Jackson2ObjectMapperFactoryBean objectMapperFactoryBean = new Jackson2ObjectMapperFactoryBean(); - objectMapperFactoryBean.setFailOnEmptyBeans( true); - objectMapperFactoryBean.setIndentOutput( true); - objectMapperFactoryBean.setDateFormat( new SimpleDateFormat( "MM/dd/yyyy")); - objectMapperFactoryBean - .setFeaturesToDisable(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES); - objectMapperFactoryBean - .setFeaturesToEnable( - com.fasterxml.jackson.core.JsonParser.Feature.ALLOW_COMMENTS, - com.fasterxml.jackson.core.JsonParser.Feature.ALLOW_SINGLE_QUOTES, - com.fasterxml.jackson.databind.DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT); - objectMapperFactoryBean.afterPropertiesSet(); - - final MappingJackson2HttpMessageConverter httpMessageConverter = new MappingJackson2HttpMessageConverter(); - httpMessageConverter.setObjectMapper(objectMapperFactoryBean.getObject()); - return httpMessageConverter; - } - - public static URI toUri( final String... pathSegments) { - return toUri(GEMFIRE_REST_API_WEB_SERVICE_URL, pathSegments); - } - - public static URI toUri( final URI baseUrl, final String... pathSegments) { - return UriComponentsBuilder.fromUri(baseUrl).pathSegment(pathSegments) - .build().toUri(); - } -} -``` - -## \#1c. Date and Time Utilities (DateTimeUtils.java) - -``` pre -package org.apache.geode.util; - - - import java.text.SimpleDateFormat; - import java.util.Calendar; - import java.util.Date; - -/** - * The DateTimeUtils class is a utility class for working with dates and times. - */ -@SuppressWarnings( "unused") - public abstract class DateTimeUtils { - - public static Calendar createCalendar( final int year, final int month, final int day) { - final Calendar dateTime = Calendar.getInstance(); - dateTime.clear(); - dateTime.set(Calendar.YEAR, year); - dateTime.set(Calendar.MONTH, month); - dateTime.set(Calendar.DAY_OF_MONTH, day); - return dateTime; - } - - public static Date createDate( final int year, final int month, final int day) { - return createCalendar(year, month, day).getTime(); - } - - public static String format( final Date dateTime, final String formatPattern) { - return (dateTime != null ? new SimpleDateFormat(formatPattern).format(dateTime) : null); - } - -} -``` - -## \#1d. Person Class (Person.java) - -``` pre -package org.apache.geode.domain; - - - import java.util.Date; - - import org.apache.geode.internal.lang.ObjectUtils; - import org.apache.geode.pdx.PdxReader; - import org.apache.geode.pdx.PdxSerializable; - import org.apache.geode.pdx.PdxWriter; - - import org.apache.geode.util.DateTimeUtils; - -/** - * The Person class is an abstraction modeling a person. - */ - - public class Person implements PdxSerializable /*ResourceSupport implements DomainObject< Long>*/ { - - private static final long serialVersionUID = 42108163264l; - - protected static final String DOB_FORMAT_PATTERN = "MM/dd/yyyy"; - - private Long id; - - private Date birthDate; - - private Gender gender; - - private String firstName; - private String middleName; - private String lastName; - - public Person() { - } - - public Person( final Long id) { - this.id = id; - } - - public Person( final String firstName, final String lastName) { - this.firstName = firstName; - this.lastName = lastName; - } - - public Person( final Long id, final String firstName, final String middleName, final String lastName, Date date, Gender gender) { - this.id = id; - this.firstName = firstName; - this.middleName = middleName; - this.lastName = lastName; - this.birthDate = date; - this.gender = gender; - } - - public Long getId() { - return id; - } - - public void setId( final Long id) { - this.id = id; - } - - public String getFirstName() { - return firstName; - } - - public void setFirstName( final String firstName) { - this.firstName = firstName; - } - - public String getLastName() { - return lastName; - } - - public void setLastName( final String lastName) { - this.lastName = lastName; - } - - public String getMiddleName() { - return middleName; - } - - public void setMiddleName( final String middleName) { - this.middleName = middleName; - } - - public Date getBirthDate() { - return birthDate; - } - - public void setBirthDate( final Date birthDate) { - this.birthDate = birthDate; - } - - public Gender getGender() { - return gender; - } - - public void setGender( final Gender gender) { - this.gender = gender; - } - - @Override - public boolean equals( final Object obj) { - if (obj == this) { - return true; - } - - if (!(obj instanceof Person)) { - return false; - } - - final Person that = (Person) obj; - - return (ObjectUtils.equals( this.getId(), that.getId()) - || (ObjectUtils.equals( this.getBirthDate(), that.getBirthDate()) - && ObjectUtils.equals( this.getLastName(), that.getLastName()) - && ObjectUtils.equals( this.getFirstName(), that.getFirstName()))); - } - - @Override - public int hashCode() { - int hashValue = 17; - hashValue = 37 * hashValue + ObjectUtils.hashCode(getId()); - hashValue = 37 * hashValue + ObjectUtils.hashCode(getBirthDate()); - hashValue = 37 * hashValue + ObjectUtils.hashCode(getLastName()); - hashValue = 37 * hashValue + ObjectUtils.hashCode(getFirstName()); - return hashValue; - } - - @Override - public String toString() { - final StringBuilder buffer = new StringBuilder( "{ type = "); - buffer.append(getClass().getName()); - buffer.append( ", id = ").append(getId()); - buffer.append( ", firstName = ").append(getFirstName()); - buffer.append( ", middleName = ").append(getMiddleName()); - buffer.append( ", lastName = ").append(getLastName()); - buffer.append( ", birthDate = ").append(DateTimeUtils.format(getBirthDate(), DOB_FORMAT_PATTERN)); - buffer.append( ", gender = ").append(getGender()); - buffer.append( " }"); - return buffer.toString(); - } - - @Override - public void fromData(PdxReader pr) { - - id = pr.readLong( "id"); - firstName = pr.readString( "firstName"); - middleName = pr.readString( "middleName"); - lastName = pr.readString( "lastName"); - birthDate = pr.readDate( "birthDate"); - gender = (Gender)pr.readObject( "gender"); - } - - @Override - public void toData(PdxWriter pw) { - pw.writeLong( "id", id); - pw.writeString( "firstName", firstName); - pw.writeString( "middleName", middleName); - pw.writeString( "lastName", lastName); - pw.writeDate( "birthDate", birthDate); - pw.writeObject( "gender", gender); - } - -} -``` - -## \#1e. Gender Class (Gender.java) - -``` pre -package org.apache.geode.domain; - -/** - * The Gender enum is a enumeration of genders (sexes). - */ - - public enum Gender { - FEMALE, - MALE -} -``` - -## \#2. Ruby REST Client (restClient.rb) - -``` pre -#!/usr/bin/ruby -w - -puts "Hello, Ruby!"; - -# !/usr/bin/env ruby - -require 'json' -require 'net/http' - -class JsonSerializable - - def to_json - hash = {} - hash["@type"] = "org.apache.geode.web.rest.domain.Person" - self.instance_variables.each do |var| - if !var.to_s.end_with?("links") - hash[var.to_s[1..-1]] = self.instance_variable_get var - end - end - hash.to_json - end - - def from_json! jsonString - JSON.load(jsonString).each do |var, val| - if !var.end_with?("type") - self.instance_variable_set "@".concat(var), val - end - end - end - -end - -class Person < JsonSerializable - - attr_accessor :id, :firstName, :middleName, :lastName, :birthDate, :gender - - def initialize(id = nil, firstName = nil, middleName = nil, lastName = nil ) - @id = id - @firstName = firstName - @middleName = middleName - @lastName = lastName - @birthDate = nil - @gender = nil - end - - def to_s - s = "{ type = Person, id = #{@id}" - s += ", firstName = #{@firstName}" - s += ", middleName = #{@middleName}" - s += ", lastName = #{@lastName}" - s += ", birthDate = #{@birthDate}" - s += ", gender = #{@gender}" - s += "}" - end - -end - -if __FILE__ == $0 - #p = Person.new(1, "Jon", "T", "Doe") - #puts p - #puts p.inspect - #puts p.to_json - - uri = URI("http://localhost:8080/gemfire-api/v1/People/1";); - - personJson = Net::HTTP::get(uri); - - # JSON from server - puts "JSON read from Server for Person with ID 1...\n #{personJson}" - - p = Person.new - p.from_json! personJson - - # print the Person to standard out - puts "Person is...\n #{p}" - - p.id = 1 - p.firstName = "Jack" - p.lastName = "Handy" - p.gender = "MALE" - - # prints modified Person to standard out - puts "Person modified is...\n #{p}" - - puts "JSON sent to Server for Person with ID 1...\n #{p.to_json}" - - Net::HTTP.start(uri.hostname, uri.port) do |http| - putRequest = Net::HTTP::Put.new uri.path, { "Content-Type" => "application/json" } - putRequest.body = p.to_json - http.request(putRequest) - end - -end -``` - -**Output from running the Ruby client:** - -``` pre -prompt# ruby restClient.rb -Hello, Ruby! -JSON read from Server for Person with ID 1... - { - "@type" : "org.gopivotal.app.domain.Person", - "id" : 1, - "firstName" : "Jane_updated", - "middleName" : "H", - "lastName" : "Doe_updated", - "gender" : "MALE", - "birthDate" : "04/12/1983" -} -Person is... - { type = Person, id = 1, firstName = Jane_updated, middleName = H, lastName = Doe_updated, birthDate = 04/12/1983, gender = MALE} -Person modified is... - { type = Person, id = 1, firstName = Jack, middleName = H, lastName = Handy, birthDate = 04/12/1983, gender = MALE} -JSON sent to Server for Person with ID 1... - {"@type":"org.apache.geode.web.rest.domain.Person","id":1,"firstName":"Jack","middleName":"H","lastName":"Handy","birthDate":"04/12/1983","gender":"MALE"} -``` - -## \#3. Python REST Client (restClient.py) - -This example uses Python 3 and shows the creation and modification of objects. It uses one external library called `requests`, which is nearly ubiquitous and avoids having to use HTTP code. - -``` pre -#!/usr/bin/env python3 - -# This is simple, repetitive and assumes you have created a region called -# "demoRegion". - -import sys -import json -import uuid -import requests - -REGION = "demoRegion" -BASE_URI = "http://localhost:8080/gemfire-api/v1"; - -headers = {'content-type': 'application/json'} - -person = {'type': 'Person', - 'firstName': 'John', - 'middleName': 'Q', - 'lastName': 'Public', - 'birthDate': '1 Jan 1900'} - - -def resource_uri(res=None, region=REGION): - if res: - return "%s/%s/%s" % (BASE_URI, region, res) - return "%s/%s" % (BASE_URI, region) - - -print("[*] First, we'll empty out our demo region - DELETE %s" % - requests.delete(resource_uri())) - -r = requests.delete(resource_uri()) -r.raise_for_status() - -print("[*] Now, we'll create 5 demo objects") - -keys = [] - -for i in range(1, 6): - key = uuid.uuid1() - - keys.append(key) - person['uuid'] = str(key) - - print("\t Creating object with key: POST %s" % key) - r = requests.post(resource_uri(), data=json.dumps(person), - params={'key': key}, - headers=headers) - r.raise_for_status() - -print("[*] List our keys - GET %s" % resource_uri("keys")) - -r = requests.get(resource_uri("keys")) -print(r.text) - -print("[*] Here's all our data - GET %s" % resource_uri()) - -r = requests.get(resource_uri()) -print(r.text) - -print("[*] Now each key one by one") - -for key in keys: - print("Fetching key - GET %s" % resource_uri(res=key)) - r = requests.get(resource_uri(res=key)) - print(r.text) - -print("[*] Now grab one, change the first name to 'Jane' and save it") - -print(" GET - %s" % resource_uri(res=keys[0])) -r = requests.get(resource_uri(res=keys[0])) -p = json.loads(r.text) -p['firstName'] = 'Jane' -print(" PUT - %s" % resource_uri(res=keys[0])) -r = requests.put(resource_uri(res=keys[0]), data=json.dumps(p), - headers=headers) - -print(" GET - %s" % resource_uri(res=keys[0])) -r = requests.get(resource_uri(res=keys[0])) -print(r.text) -```
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/rest_functions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/rest_functions.html.md.erb b/geode-docs/rest_apps/rest_functions.html.md.erb deleted file mode 100644 index 0dc001a..0000000 --- a/geode-docs/rest_apps/rest_functions.html.md.erb +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Function Endpoints ---- - -Geode functions allows you to write and execute server-side transactions and data operations. These may include anything ranging from initializing components or third-party services or aggregating data. - -- **[GET /gemfire-api/v1/functions](../rest_apps/get_functions.html)** - - List all registered Geode functions in the cluster. - -- **[POST /gemfire-api/v1/functions/{functionId}](../rest_apps/post_execute_functions.html)** - - Execute Geode function on entire cluster or on a specified region, members and member groups. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/rest_prereqs.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/rest_prereqs.html.md.erb b/geode-docs/rest_apps/rest_prereqs.html.md.erb deleted file mode 100644 index ecf21b9..0000000 --- a/geode-docs/rest_apps/rest_prereqs.html.md.erb +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Prerequisites and Limitations for Writing REST Applications ---- - -Before development, understand the prerequisites and limitations of the current REST implementation in Geode. - -Geode and REST-enabled applications accessing Geode are subject to the following rules and limitations: - -- All domain objects, functions and function-arg classes must be properly configured and registered in the Geode deployment. Any functions that you wish to execute through the REST API must be available on the target memberâs CLASSPATH. -- The current implementation only supports the **application/json** MIME type. At time of publication, any other return types (XML, objects, and so on) are not supported. Plain text is supported as a return type for some error messages. -- Keys are strictly of type String for this release. For example, the request `PUT http://localhost:8080/gemfire-api/v1/customers/123.456` will add entry for key ("123.456") of type String. -- Some special formats of JSON documents are not supported in Geode REST. See [Key Types and JSON Support](troubleshooting.html#concept_gsv_zd5_m4) for examples. -- To achieve interoperability between Geode Java clients (or Geode native clients) and REST clients, the following rules must be followed: - - All Geode Java and native client classes operating on data also accessed by the REST interface must be PDX serialized either via PDX autoserialization or by implementing `PdxSerializable`. - - Geode Java clients and native clients can retrieve REST-enabled data either as a `PdxInstance` or as an actual object by using the `PdxInstance.getObject` method. If you use the latter method, first you must declare the object type (@type) in your POST or PUT request payload when creating the object in REST; and secondly, the Java client must have the actual domain class in its CLASSPATH. -- Objects returned by REST-invoked functions must be returned as PdxInstance objects or other data types that can be written to JSON. You cannot return Java objects. -- REST client applications do not support single hop access or notification features. -- Specifying subregions as endpoints is not currently supported. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/rest_queries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/rest_queries.html.md.erb b/geode-docs/rest_apps/rest_queries.html.md.erb deleted file mode 100644 index 0a0aec0..0000000 --- a/geode-docs/rest_apps/rest_queries.html.md.erb +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Query Endpoints ---- - -Geode uses a query syntax based on OQL (Object Query Language) to query region data. Since Geode regions are key-value stores, values can range from simple byte arrays to complex nested objects. - -- **[GET /gemfire-api/v1/queries](../rest_apps/get_queries.html)** - - List all parameterized queries by ID or name. - -- **[POST /gemfire-api/v1/queries?id=<queryId>&q=<OQL-statement>](../rest_apps/post_create_query.html)** - - Create (prepare) the specified parameterized query and assign the corresponding ID for lookup. - -- **[POST /gemfire-api/v1/queries/{queryId}](../rest_apps/post_execute_query.html)** - - Execute the specified named query passing in scalar values for query parameters in the POST body. - -- **[PUT /gemfire-api/v1/queries/{queryId}](../rest_apps/put_update_query.html)** - - Update a named, parameterized query. - -- **[DELETE /gemfire-api/v1/queries/{queryId}](../rest_apps/delete_named_query.html)** - - Delete the specified named query. - -- **[GET /gemfire-api/v1/queries/adhoc?q=<OQL-statement>](../rest_apps/get_execute_adhoc_query.html)** - - Run an unnamed (unidentified), ad-hoc query passed as a URL parameter. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/rest_regions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/rest_regions.html.md.erb b/geode-docs/rest_apps/rest_regions.html.md.erb deleted file mode 100644 index ea107c8..0000000 --- a/geode-docs/rest_apps/rest_regions.html.md.erb +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Region Endpoints ---- - -A Geode region is how Geode logically groups data within its cache. Regions stores data as entries, which are key-value pairs. Using the REST APIs you can read, add (or update), and delete region data. - -See also [Data Regions](../basic_config/data_regions/chapter_overview.html#data_regions) for more information on working with regions. - -- **[GET /gemfire-api/v1](../rest_apps/get_regions.html)** - - List all available resources (regions) in the Geode cluster. - -- **[GET /gemfire-api/v1/{region}](../rest_apps/get_region_data.html)** - - Read data for the region. The optional limit URL query parameter specifies the number of values from the Region that will be returned. The default limit is 50. If the user specifies a limit of âALLâ, then all entry values for the region will be returned. - -- **[GET /gemfire-api/v1/{region}/keys](../rest_apps/get_region_keys.html)** - - List all keys for the specified region. - -- **[GET /gemfire-api/v1/{region}/{key}](../rest_apps/get_region_key_data.html)** - - Read data for a specific key in the region. - -- **[GET /gemfire-api/v1/{region}/{key1},{key2},...,{keyN}](../rest_apps/get_region_data_for_multiple_keys.html)** - - Read data for multiple keys in the region. - -- **[HEAD /gemfire-api/v1/{region}](../rest_apps/head_region_size.html)** - - An HTTP HEAD request that returns region's size (number of entries) within the HEADERS, which is a response without the content-body. Region size is specified in the pre-defined header named "Resource-Count". - -- **[POST /gemfire-api/v1/{region}?key=<key>](../rest_apps/post_if_absent_data.html)** - - Create (put-if-absent) data in region. - -- **[PUT /gemfire-api/v1/{region}/{key}](../rest_apps/put_update_data.html)** - - Update or insert (put) data for key in region. - -- **[PUT /gemfire-api/v1/{region}/{key1},{key2},...{keyN}](../rest_apps/put_multiple_values_for_keys.html)** - - Update or insert (put) data for multiple keys in the region. - -- **[PUT /gemfire-api/v1/{region}/{key}?op=REPLACE](../rest_apps/put_replace_data.html)** - - Update (replace) data with key(s) if and only if the key(s) exists in region. The Key(s) must be present in the Region for the update to occur. - -- **[PUT /gemfire-api/v1/{region}/{key}?op=CAS](../rest_apps/put_update_cas_data.html)** - - Update (compare-and-set) value having key with a new value if and only if the "@old" value sent matches the current value having key in region. - -- **[DELETE /gemfire-api/v1/{region}](../rest_apps/delete_all_data.html)** - - Delete all entries in the region. - -- **[DELETE /gemfire-api/v1/{region}/{key}](../rest_apps/delete_data_for_key.html)** - - Delete entry for specified key in the region. - -- **[DELETE /gemfire-api/v1/{region}/{key1},{key2},...{keyN}](../rest_apps/delete_data_for_multiple_keys.html)** - - Delete entries for multiple keys in the region. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/setup_config.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/setup_config.html.md.erb b/geode-docs/rest_apps/setup_config.html.md.erb deleted file mode 100644 index e0daa48..0000000 --- a/geode-docs/rest_apps/setup_config.html.md.erb +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Setup and Configuration ---- - -The Apache Geode developer REST interface runs as an embedded HTTP or HTTPS service (Jetty server) within a Geode data node. - -All Geode REST interface classes and required JAR files are distributed as a WAR file with the Geode product distribution. You can locate the file in the following location: - -``` pre -$GEMFIRE/tools/Extensions/gemfire-api.war -``` - -To enable the developer REST API service in Apache Geode, set the `start-dev-rest-api` Geode property to `true` when starting a data node using either `gfsh` or the ServerLauncher API. Setting this property to true on a data node will start up an embedded Jetty server and deploy the REST developer API WAR file. - -**Note:** -The REST API service for application development can only be started on servers; you cannot use locators to host the developer Geode REST API services. - -You can have multiple REST enabled data nodes in a single distributed system. Each data node should have a separate host name and unique end point. To ensure that the data node is reachable on a machine with multiple NIC addresses, you can use `http-service-bind-address` to bind an address to the REST API service (as well as the other embedded web services such as Pulse.) - -You can also configure the Developer REST API service to run over -HTTPS by enabling ssl for the `http` component in `gemfire.properties` -or `gfsecurity.properties` or on server startup: -See [SSL](../managing/security/ssl_overview.html) for details on configuring SSL parameters. -These SSL parameters apply to all HTTP services hosted on the configured server, which can include the following: - -- Developer REST API service -- Management REST API service (for remote cluster management) -- Pulse monitoring tool - -The following procedure starts up a REST API service-enabled Geode deployment: - -1. Configure PDX for your cluster. You must configure PDX if either or both of the following conditions apply: - - Application peer member caches will access REST-accessible Regions (resources) with the `Region.get(key)`. - - Your deployment has persistent regions that must be available as resources to the REST API. To configure PDX in your cluster, perform the following steps: - 1. Start up a locator running the [cluster configuration service](../configuring/cluster_config/gfsh_persist.html) (enabled by default). For example: - - ``` pre - gfsh>start locator --name=locator1 - ``` - 2. If your deployment has application peer member caches (for example, Java clients) that must also access REST-accessible Regions (resources), use the following gfsh command: - - ``` pre - gfsh>configure pdx --read-serialized=true - ``` - **Note:** - You do not need to configure `--read-serialized=true` if no application peer member caches are accessing the REST-accessible regions (resources) in your deployment. - 3. If your deployment contains **persistent regions** that must be REST-accessible, use the following gfsh command: - - ``` pre - gfsh>configure pdx --disk-store - ``` - This command sets `pdx` `persistent` equal to true and sets the disk-store-name to DEFAULT. If desired, specify an existing disk store name as the value for `--disk-store`. - 4. If both of the above cases apply to your deployment, then configure PDX with the following single command: - - ``` pre - gfsh>configure pdx --read-serialized=true --disk-store - ``` - - After you have configured PDX for your caches, then proceed with starting up your REST-enabled servers and other data nodes. - -2. Start a server node with the Geode property `start-dev-rest-api` set to `true`. For example: - - ``` pre - gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \ - --J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost - ``` - - Optionally, you can also configure a `http-service-bind-address` and `http-service-port` to identify the cache server and specific port that will host REST services. If you do not specify the `http-service-port`, the default port is 7070. If you do not specify `http-service-bind-address`, the HTTP service will bind to all local addresses by default. - - Any server that hosts data, even a server acting as a JMX manager, can start the developer REST API service. For example, to start the service on a server that is also a JMX manager, you would run: - - ``` pre - gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \ - --J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost \ - --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true - ``` - - Note that when started as a JMX Manager, the server will also host the Pulse web application in the same HTTP service. - -3. You may also need to specify a CLASSPATH to load any functions that need to be made available to your REST services. For example: - - ``` pre - gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \ - --J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost \ - --classpath=/myapps/testfunctions.jar - ``` - -4. You can also specify these properties either upon server startup or in the serverâs gemfire.properties configuration file. - - ``` pre - gfsh>start server --name=serverX --server-port=40405 --cache-xml-file=cache-config.xml \ - --properties-file=gemfire.properties --classpath=/myapps/testfunctions.jar - ``` - - where gemfire.properties contains: - - ``` pre - http-service-port=8080 - http-service-bind-address=localhost - start-dev-rest-api=true - ``` - -5. Verify that the Geode REST API service is up and running. To validate this, you can perform the following checks: - 1. Test the list resources endpoint (this step assumes that you have regions defined on your cluster): - - ``` pre - curl -i http://localhost:8080/gemfire-api/v1 - ``` - - 2. Examine the server logs for the following messages: - - ``` pre - [info 2014/06/12 14:56:52.431 PDT rest-test <localhost-startStop-1> tid=0x4d] - (tid=11 msgId=8) Initializing Spring FrameworkServlet 'gemfire-api'[info 2014/06/12 - 14:56:52.432 PDT rest-test <localhost-startStop-1> tid=0x4d] (tid=11 msgId=9) - FrameworkServlet 'gemfire-api': initialization started - ``` - - 3. Open a browser and enter the following URL to browse the Swagger-enabled REST APIs: - - ``` pre - http://<http-service-bind-address>:<http-service-port>/gemfire-api/docs/index.html - ``` - - where *http-service-bind-address* is the address and *http-service-port* is the port number that you specified when starting the Development REST API service on the server. For example, based on the server started in step 2, you would enter: - - ``` pre - http://localhost:8080/gemfire-api/docs/index.html - ``` - - If you did not specify these properties upon server startup or in `gemfire.properties`, then use the default of localhost and port 7070. See [Using the Swagger UI to Browse REST APIs](using_swagger.html#concept_rlr_y3c_54) for more information. - -## Programmatic Startup - -You can also start up and configure Geode REST services programmatically. For example: - -``` pre - import org.apache.geode.distributed.ServerLauncher; - - public class MyEmbeddedRestServer { - - public static void main(String[] args){ - ServerLauncher serverLauncher = new ServerLauncher.Builder() - .set("start-dev-rest-api", "true") - .set("http-service-port", "8080") - .set("http-service-bind-address", "localhost") - .setPdxReadSerialized(true) - .build(); - - serverLauncher.start(); - - System.out.println("REST server successfully started"); - } - } -``` -You can then verify that the developer REST API service has been started programmatically by visiting the following URL: - -``` pre -http://localhost:8080/gemfire-api/docs/index.html -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/troubleshooting.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/troubleshooting.html.md.erb b/geode-docs/rest_apps/troubleshooting.html.md.erb deleted file mode 100644 index c35e051..0000000 --- a/geode-docs/rest_apps/troubleshooting.html.md.erb +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Troubleshooting and FAQ ---- -<a id="topic_r5z_lj5_m4"></a> - - -This section provides troubleshooting guidance and frequently asked questions about Geode Developer REST APIs. - -- **[Key Types and JSON Support](../rest_apps/troubleshooting.html#concept_gsv_zd5_m4)** - - When defining regions (your REST resources), you must only use scalar values for keys and also set value constraints in order to avoid producing JSON that cannot be parsed by Geode. - -## Checking if the REST API Service is Up and Running - -Use the ping endpoint to verify whether the REST API server is available. - -Use the `/gemfire-api/v1/ping` endpoint to check REST API server availability: - -For example: - -``` pre -curl -i http://localhost:7070/gemfire-api/v1/ping -``` - -Example success response: - -``` pre -200 OK -``` - -If the server is not available, your client will receive an HTTP error code and message. - -## Key Types and JSON Support - -When defining regions (your REST resources), you must only use scalar values for keys and also set value constraints in order to avoid producing JSON that cannot be parsed by Geode. - -If Geode regions are not defined with scalar values as keys and value constraints, then you may receive the following error message (even though the JSON is technically valid) in your REST client applications: -``` pre -Json doc specified in request body is malformed..!!' -``` - -For example, the following JSON documents are not supported by Geode: - -## Unsupported JSON Example 1 - -``` pre -[ - 1, - [], - [ - 4, - "hello", - {} - ], - { - "array": [] - } -] -``` - -## Unsupported JSON Example 2 - -``` pre -[[[[[[[[[[[[[[[[[[["Not too deep"]]]]]]]]]]]]]]]]]]] -``` - -## Unsupported JSON Example 3 - -``` pre -[1,2,3,"hello"] -``` - -## Unsupported JSON Example 4 - -``` pre -[ - "JSON Test Pattern pass1", - { - "object with 1 member": [ - "array with 1 element" - ] - }, - {}, - [], - -42, - true, - false, - null, - { - "integer": 1234567890, - "real": -9876.54321, - "e": 1.23456789e-13, - "E": 1.23456789e+34, - "": 2.3456789012e+76, - "zero": 0, - "one": 1, - "space": " ", - "quote": "\"", - "backslash": "\\", - "controls": "\b\f\n\r\t", - "slash": "/ & /", - "alpha": "abcdefghijklmnopqrstuvwyz", - "ALPHA": "ABCDEFGHIJKLMNOPQRSTUVWYZ", - "digit": "0123456789", - "0123456789": "digit", - "special": "`1~!@#$%^&*()_+-={':[,]}|;.</>?", - "true": true, - "false": false, - "null": null, - "array": [], - "object": {}, - "address": "50 St. James Street", - "url": "http://www.JSON.org/";, - "comment": "// /* <!-- --", - "# -- --> */": " ", - " s p a c e d ": [ - 1, - 2, - 3, - 4, - 5, - 6, - 7 - ], - "compact": [ - 1, - 2, - 3, - 4, - 5, - 6, - 7 - ], - "jsontext": "{\"object with 1 member\":[\"array with 1 element\"]}", - "quotes": "" \" %22 0x22 034 "", - "/\\\"\b\f\n\r\t`1~!@#$%^&*()_+-=[]{}|;:',./<>?": "A key can be any string" - }, - 0.5, - 98.6, - 99.44, - 1066, - 10, - 1, - 0.1, - 1, - 2, - 2, - "rosebud" -] -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/rest_apps/using_swagger.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/rest_apps/using_swagger.html.md.erb b/geode-docs/rest_apps/using_swagger.html.md.erb deleted file mode 100644 index 6a67635..0000000 --- a/geode-docs/rest_apps/using_swagger.html.md.erb +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Using the Swagger UI to Browse REST APIs ---- - -Apache Geode Developer REST APIs are integrated with the Swagger⢠framework. This framework provides a browser-based test client that allows you to visualize and try out Geode REST APIs. - -Swagger application JARs are included in the Geode REST application WAR; you do not need to install any additional libraries to use Swagger. - -The following example demonstrates how to access the Swagger UI to browse the APIs. - -1. Start a Geode Developer REST API-enabled server and JMX Manager as described in [Setup and Configuration](setup_config.html#topic_e21_qc5_m4). For example: - - ``` pre - gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \ - --J=-Dgemfire.http-service-bind-address=localhost \ - --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true - ``` - - If desired, you can specify a different HTTP port for the developer REST service. For example, `-J=-Dgemfire.http-service-port=8080`. If you do not specify this property, the service is available at the default port 7070. - -2. To access Swagger, open a browser and enter the following URL: For example: - - ``` pre - http://localhost:7070/gemfire-api/docs/index.html - ``` - - The following Web page appears: <img src="../images/swagger_home.png" id="concept_rlr_y3c_54__image_m15_qcm_x4" class="image" /> - -3. In gfsh, connect to the server running the JMX Manager. - - ``` pre - gfsh>connect --jmx-manager=localhost[1099] - ``` - -4. Using gfsh, create one or more regions on the REST API server. For example: - - ``` pre - gfsh>create region --name=region1 --type=REPLICATE --key-constraint=java.lang.String - Member | Status - ------- | ------------------------------------------ - server1 | Region "/region1" created on "server1" - ``` - -5. In Swagger, click on **region : region** to list all the available endpoints for accessing regions. -6. In the list of **region** endpoints, click on the **GET /v1** endpoint link. The page displays additional request and response information about the API. <img src="../images/swagger_v1.png" id="concept_rlr_y3c_54__image_kx2_2dm_x4" class="image" /> -7. Click the **Try it out!** button. Any regions you added in step 5 are returned in the response body. <img src="../images/swagger_v1_response.png" id="concept_rlr_y3c_54__image_y2p_tdm_x4" class="image" /> -8. Add an entry to the region by expanding the **POST /v1/{region}** endpoint. <img src="../images/swagger_post_region.png" id="concept_rlr_y3c_54__image_sfk_c2m_x4" class="image" /> -9. Click the **Try it out!** button to see the response body and response code. <img src="../images/swagger_post_region_response.png" id="concept_rlr_y3c_54__image_pmx_k2m_x4" class="image" /> - -You can use the Swagger interface to try out additional Geode API endpoints and view sample responses. - -For more information on Swagger, see [https://helloreverb.com/developers/swagger](https://helloreverb.com/developers/swagger) and the Swagger Specification at [https://github.com/wordnik/swagger-spec/](https://github.com/wordnik/swagger-spec/). - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/book_intro.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/book_intro.html.md.erb b/geode-docs/tools_modules/book_intro.html.md.erb deleted file mode 100644 index 962f551..0000000 --- a/geode-docs/tools_modules/book_intro.html.md.erb +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Tools and Modules ---- - -*Tools and Modules* describes tools and modules associated with Apache Geode. - -<a id="deploy_run__section_tool_intro"></a> - -- **[gfsh (Geode SHell)](../tools_modules/gfsh/chapter_overview.html)** - - Geode gfsh (pronounced "jee-fish") provides a single, powerful command-line interface from which you can launch, manage, and monitor Geode processes, data, and applications. - -- **[Gemcached](../tools_modules/gemcached/chapter_overview.html)** - - Gemcached is a Geode adapter that allows Memcached clients to communicate with a Geode server cluster, as if the servers were memcached servers. Memcached is an open-source caching solution that uses a distributed, in-memory hash map to store key-value pairs of string or object data. - -- **[Hibernate Cache Module](../tools_modules/hibernate_cache/chapter_overview.html)** - - The Geode Hibernate Cache Module provides fast, scalable, distributed L2 caching for Hibernate. - -- **[HTTP Session Management Modules](../tools_modules/http_session_mgmt/chapter_overview.html)** - - The Apache Geode HTTP Session Management modules provide fast, scalable, and reliable session replication for HTTP servers without requiring application changes. - -- **[Geode Pulse](../tools_modules/pulse/chapter_overview.html)** - - Geode Pulse is a Web Application that provides a graphical dashboard for monitoring vital, real-time health and performance of Geode clusters, members, and regions. - -- **[Geode Redis Adapter](../tools_modules/redis_adapter.html)** - - The Geode Redis adapter allows Geode to function as a drop-in replacement for a Redis data store, letting Redis applications take advantage of Geodeâs scaling capabilities without changing their client code. Redis clients connect to a Geode server in the same way they connect to a Redis server, using an IP address and a port number. - - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gemcached/about_gemcached.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gemcached/about_gemcached.html.md.erb b/geode-docs/tools_modules/gemcached/about_gemcached.html.md.erb deleted file mode 100644 index 186ce05..0000000 --- a/geode-docs/tools_modules/gemcached/about_gemcached.html.md.erb +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: How Gemcached Works ---- - -Applications use memcached clients to access data stored in embedded Gemcached servers. - -Applications can use memcached clients that are written in Python, C\#, Ruby, PHP, and other programming languages. Each memcached server in a cluster stores data as key/value pairs. A memcached client maintains a list of these servers, determines which server has the required data, and accesses the data directly on that server. - -To integrate memcached with Apache Geode, you embed a Gemcached server within a Geode cache server. These *Gemcached* servers take the place of memcached servers. The memcached client uses its normal wire protocol to communicate with the Gemcached servers, which appear to the client as memcached servers. No code changes in the clients are needed. Geode manages the distribution and access to data among the embedded Gemcached servers. - -As shown in [Gemcached Architecture](about_gemcached.html#concept_4C654CA7F6B34E4CA1B0318BC9644536__fig_8BF351B5FAF1490F8B0D0E7F3098BC73), memcached clients, which ordinarily maintain a list of memcached servers, now maintain a list of embedded Gemcached servers. If more embedded Gemcached servers are added to the cluster, the new servers automatically become part of the cluster. The memcached clients can continue to communicate with the servers on the list, without having to update their list of servers. - -<a id="concept_4C654CA7F6B34E4CA1B0318BC9644536__fig_8BF351B5FAF1490F8B0D0E7F3098BC73"></a> -<span class="figtitleprefix">Figure: </span>Gemcached Architecture - -<img src="../../images/Gemcached.png" id="concept_4C654CA7F6B34E4CA1B0318BC9644536__image_98B6222F29B940CD93381D03325C4455" class="image" /> - -Memcached clients use the memcached API to read and write data that is stored in memcached servers; therefore, client-side Geode features are not available to these clients. Gemcached servers, however, can use Geode's server-side features and API. These features include the following. (For more detail, see [Advantages of Gemcached over Memcached](advantages.html#topic_849581E507544E63AF23793FBC47D778).) - -- Data consistency and scalability. -- High availability. -- Read-through, write through, and write behind to a database, implemented from within the distributed Geode cache. -- Storage keys and values of any type and size. -- For applications, a choice among partitioned and replicated region configurations. -- Automatic overflow of data to disk in low-memory scenarios. -- Efficient persistence of data to disk. -- Configurable expiration of cached data. -- Configurable eviction of cached data. - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gemcached/advantages.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gemcached/advantages.html.md.erb b/geode-docs/tools_modules/gemcached/advantages.html.md.erb deleted file mode 100644 index dcb93b9..0000000 --- a/geode-docs/tools_modules/gemcached/advantages.html.md.erb +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Advantages of Gemcached over Memcached ---- - -The standard memcached architecture has inherent architectural challenges that make memcached applications difficult to write, maintain, and scale. Using Gemcached with Geode addresses these challenges. - -**Data consistency**. Memcached clients must maintain a list of servers where the distributed data is stored. Each client must maintain an identical list, with each list ordered in the same way. It is the responsibility of the application logic to maintain and propagate this list. If some clients do not have the correct list, the client can retrieve stale data. In Geode clusters, all members communicate with each other to maintain data consistency, which eliminates the need to code these behaviors in the memcached clients. - -**High availability**. When a memcached server becomes unavailable, memcached clusters are subject to failures or degraded performance because clients must directly query the backend database. Memcached-based applications must be coded to handle these failures, while Geode clusters handle such failures natively. - -**Faster cluster startup time**. When a memcached cluster fails and a restart is required, the data must be reloaded and distributed to the cluster members while simultaneously processing requests for data. These startup activities can be time-consuming. When a Geode cluster restarts, data can be reloaded from other in-memory, redundant copies of the data or from disk, without having to query the back end database. - -**Better handling of network segmentation**. Large deployments of memcached can use hundreds of servers to manage data. If, due to network segmentation, some clients cannot connect to all nodes of a partition, the clients will have to fetch the data from the backend database to avoid hosting stale data. Geode clusters handle network segmentation to ensure that client responses are consistent. - -**Automatic scalability**. If you need to add capacity to a memcached cluster, you must propagate a new server list to all clients. As new clients come on line with the new list, older clients may not have a consistent view of the data in the cluster, which can result in inconsistent data in the servers. Because new Geode cache server members automatically discover each other, memcached clients do not need to maintain a complete server list. You can add capacity simply by adding servers. - -**Scalable client connections**. A memcached client may need to access multiple pieces of data stored on multiple servers, which can result in clients having a TCP connection open to every server. When a memcached client accesses a Gemcached server, only a single connection to a Gemcached server instance is required. The Gemcached server manages the distribution of data using Geode's standard features. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gemcached/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gemcached/chapter_overview.html.md.erb b/geode-docs/tools_modules/gemcached/chapter_overview.html.md.erb deleted file mode 100644 index 76d0a1a..0000000 --- a/geode-docs/tools_modules/gemcached/chapter_overview.html.md.erb +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Gemcached ---- -<a id="topic_3751C8A924884B7F88F993CAD350D4FE"></a> - - -Gemcached is a Geode adapter that allows Memcached clients to communicate with a Geode server cluster, as if the servers were memcached servers. Memcached is an open-source caching solution that uses a distributed, in-memory hash map to store key-value pairs of string or object data. - -For information about Memcached, see [http://www.memcached.org](http://www.memcached.org). - -- **[How Gemcached Works](about_gemcached.html)** - - Applications use memcached clients to access data stored in embedded Gemcached servers. - -- **[Deploying and Configuring a Gemcached Server](deploying_gemcached.html)** - - You can configure and deploy Gemcached servers in a Java class or by using the gfsh command-line interface. - -- **[Advantages of Gemcached over Memcached](advantages.html)** - - The standard memcached architecture has inherent architectural challenges that make memcached applications difficult to write, maintain, and scale. Using Gemcached with Geode addresses these challenges. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gemcached/deploying_gemcached.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gemcached/deploying_gemcached.html.md.erb b/geode-docs/tools_modules/gemcached/deploying_gemcached.html.md.erb deleted file mode 100644 index b2fbc00..0000000 --- a/geode-docs/tools_modules/gemcached/deploying_gemcached.html.md.erb +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Deploying and Configuring a Gemcached Server ---- - -You can configure and deploy Gemcached servers in a Java class or by using the gfsh command-line interface. - -The following sections describe how to configure and deploy an embedded Gemcached server. You can configure and start a GemCached server either by invoking a Java class that calls the cache server's `start()` method, or by starting the cache server using the gfsh command line. - -## <a id="topic_7B158074B27A4FEF9D38E7C369905C72__section_17E7E4058D914334B9C5AC2E3DC1F7F2" class="no-quick-link"></a>Embedding a Gemcached server in a Geode Java Application - -The `org.apache.geode.memcached` package contains a single class, `GemFireMemcachedServer`. (See the [Geode Javadocs](http://static.springsource.org/spring-gemfire/docs/current/api/).) Use this class to configure and embed a Gemcached server in a Geode cache server. For example, the following statement creates and starts an embedded Gemcached server on port number 5555 using the binary protocol: - -``` pre -GemFireMemcachedServer server = - new GemFireMemcachedServer(5555, Protocol.BINARY);server.start(); - -``` - -**Note:** -By default, Gemcached servers use the ASCII protocol. - -When you start a Gemcached server, by default, it creates a `RegionShortcut.PARTITION` region named `gemcached` where data used by memcached clients is stored. You can alter these defaults by configuring the region using the `cache.xml` or `gemfire.properties` files. See [Distributed System and Cache Configuration](../../basic_config/config_concepts/chapter_overview.html). - -## <a id="topic_7B158074B27A4FEF9D38E7C369905C72__section_58A3FFED5BBB4F92A79FBD50421DC3F3" class="no-quick-link"></a>Starting a Gemcached Server Using a gfsh Command - -You can also start a Gemcached server with the gfsh command-line interface. Use the following syntax: - -``` pre -gfsh>start server - --name=<server_name> - --server-port=<port_number> - --memcached-port=<port_number> - --memcached-protocol=BINARY|ASCII -``` - -**Note:** -You can also set the memcached port number and protocol in the `gemfire.properties` file. - -If the `memcached-port` property is not specified, the embedded Gemcached server is not started. - -## <a id="topic_7B158074B27A4FEF9D38E7C369905C72__section_E5587FE56A21424FBAEE8CF61DF34219" class="no-quick-link"></a>Configuring a Gemcached Server with the gemfire.properties File - -You can set the following properties in the `gemfire.properties` file that are used when starting Gemcached servers: - -<a id="topic_7B158074B27A4FEF9D38E7C369905C72__table_3F586259E06E42C4BD82AD661B3AFEA4"></a> - -<table> -<caption><span class="tablecap">Table 1. Gemcached Properties</span></caption> -<colgroup> -<col width="50%" /> -<col width="50%" /> -</colgroup> -<thead> -<tr class="header"> -<th><p>Property</p></th> -<th><p>Description</p></th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td><code class="ph codeph">memcached-port</code></td> -<td><p>The port number where the Gemcached server listens for connections from memcached clients.</p> -<p>If the port number is set to 0 or the <code class="ph codeph">memcached-port</code> parameter is omitted, the Gemcached server does not start.</p></td> -</tr> -<tr class="even"> -<td><code class="ph codeph">memcached-protocol</code></td> -<td><p>Memcached supports both ASCII and binary communication protocols. -(See <a href="https://github.com/memcached/memcached/blob/master/doc/protocol.txt";>Memcached protocol</a> By default, Gemcached uses the ASCII protocol.</p> -<p>Set one of the following values:</p> -<ul> -<li><code class="ph codeph">ASCII</code> (default)</li> -<li><code class="ph codeph">BINARY</code></li> -</ul></td> -</tr> -</tbody> -</table> - -<span class="tablecap">Table 1. Gemcached Properties</span> - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gfsh/about_gfsh.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gfsh/about_gfsh.html.md.erb b/geode-docs/tools_modules/gfsh/about_gfsh.html.md.erb deleted file mode 100644 index 68e2499..0000000 --- a/geode-docs/tools_modules/gfsh/about_gfsh.html.md.erb +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: What You Can Do with gfsh ---- - -`gfsh` supports the administration, debugging, and deployment of Apache Geode processes and applications. - -With `gfsh`, you can: - -- Start and stop Apache Geode processes, such as locators and cache servers -- Start and stop gateway sender and gateway receiver processes -- Deploy applications -- Create and destroy regions -- Execute functions -- Manage disk stores -- Import and export data -- Monitor Apache Geode processes -- Launch Apache Geode monitoring tools - -The `gfsh` command line interface lets developers spend less time configuring cache instance XML, properties, logs, and statistics. gfsh commands generate reports; capture cluster-wide statistics; and support the export of statistics, logs, and configurations. Like Spring Roo, gfsh features command completion (so you do not have to know the syntax), context-sensitive help, scripting, and the ability to invoke any commands from within an application by using a simple API. The gfsh interface uses JMX/RMI to communicate with Apache Geode processes. - -You can connect gfsh to a remote distributed system using the HTTP protocol. See [Using gfsh to Manage a Remote Cluster Over HTTP or HTTPS](../../configuring/cluster_config/gfsh_remote.html). - -By default, the cluster configuration service saves the configuration of your Apache Geode cluster as you create Apache Geode objects using gfsh. You can export this configuration and import it into another Apache Geode cluster. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html#concept_r22_hyw_bl). - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gfsh/cache_xml_2_gfsh.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gfsh/cache_xml_2_gfsh.html.md.erb b/geode-docs/tools_modules/gfsh/cache_xml_2_gfsh.html.md.erb deleted file mode 100644 index 2724bdc..0000000 --- a/geode-docs/tools_modules/gfsh/cache_xml_2_gfsh.html.md.erb +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Mapping cache.xml Elements to gfsh Configuration Commands ---- - -You can configure a Geode cluster using either cache.xml files, -or you can use gfsh and the cluster configuration service -to configure a cluster. -This table maps `cache.xml` elements to the gfsh commands that -configure and manage a cluster. - -<a id="reference_qvw_zyq_54__table_in3_dzq_54"></a> - -<table> -<colgroup> -<col width="50%" /> -<col width="50%" /> -</colgroup> -<thead> -<tr class="header"> -<th>cache.xml Element</th> -<th>gfsh Command</th> -</tr> -</thead> -<tbody> -<tr class="odd"> -<td><cache>, <cache-server></td> -<td><ul> -<li><a href="command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A">start server</a></li> -<li><a href="command-pages/status.html#topic_E5DB49044978404D9D6B1971BF5D400D">status server</a></li> -<li><a href="command-pages/stop.html#topic_723EE395A63A40D6819618AFC2902115">stop server</a></li> -<li><a href="command-pages/alter.html#topic_7E6B7E1B972D4F418CB45354D1089C2B">alter runtime</a></li> -</ul></td> -</tr> -<tr class="even"> -<td><async-event-queue></td> -<td><ul> -<li><a href="command-pages/create.html#topic_ryz_pb1_dk">create async-event-queue</a></li> -<li><a href="command-pages/list.html#topic_j22_kzk_2l">list async-event-queues</a></li> -</ul></td> -</tr> -<tr class="odd"> -<td><pdx></td> -<td><ul> -<li><a href="command-pages/configure.html#topic_jdkdiqbgphqh">configure pdx</a></li> -</td> -</tr> -<tr class="even"> -<td><region></td> -<td><ul> -<li><a href="command-pages/create.html#topic_54B0985FEC5241CA9D26B0CE0A5EA863">create region</a></li> -<li><a href="command-pages/alter.html#topic_E74ED23CB60342538B2175C326E7D758">alter region</a></li> -<li><a href="command-pages/destroy.html#topic_BEDACECF4599407794ACBC0E56B30F65">destroy region</a></li> -<li><a href="command-pages/describe.html#topic_DECF7D3D33F54071B6B8AD4EA7E3F90B">describe region</a></li> -<li><a href="command-pages/list.html#topic_F0ECEFF26086474498598035DD83C588">list regions</a></li> -<li><a href="command-pages/rebalance.html">rebalance</a></li> -</ul></td> -</tr> -<tr class="odd"> -<td><index></td> -<td><ul> -<li><a href="command-pages/create.html#topic_960A5B6FD3D84E1881EE118E299DD12D">create index</a></li> -<li><a href="command-pages/destroy.html#topic_D00219CCD6F64C1582A0802AC5CDF3F3">destroy index</a></li> -<li><a href="command-pages/list.html#topic_B3B51B6DEA484EE086C4F657EC9831F2">list indexes</a></li> -</ul></td> -</tr> -<tr class="even"> -<td><disk-store></td> -<td><ul> -<li><a href="command-pages/create.html#topic_bkn_zty_ck">create disk-store</a></li> -<li><a href="command-pages/alter.html#topic_99BCAD98BDB5470189662D2F308B68EB">alter disk-store</a></li> -<li><a href="command-pages/backup.html#topic_E74ED23CB60342538B2175C326E7D758">backup disk-store</a></li> -<li><a href="command-pages/compact.html#topic_F113C95C076F424E9AA8AC4F1F6324CC">compact disk-store</a></li> -<li><a href="command-pages/compact.html#topic_9CCFCB2FA2154E16BD775439C8ABC8FB">compact offline-disk-store</a></li> -<li><a href="command-pages/describe.html#topic_C635B500BE6A4F1D9572D0BC98A224F2">describe disk-store</a></li> -<li><a href="command-pages/describe.html#topic_kys_yvk_2l">describe offline-disk-store</a></li> -<li><a href="command-pages/destroy.html#topic_yfr_l2z_ck">destroy disk-store</a></li> -<li><a href="command-pages/list.html#topic_BC14AD57EA304FB3845766898D01BD04">list disk-stores</a></li> -<li><a href="command-pages/revoke.html">revoke missing-disk-store</a></li> -<li><a href="command-pages/show.html#topic_7B3D624D5B4F41D1A0F8A9C3C8B2E780">show missing-disk-stores</a></li> -<li><a href="command-pages/validate.html">validate offline-disk-store</a></li> -</ul></td> -</tr> -</tbody> -</table> - -<span class="tablecap">Table 1. Migrating cache.xml elements to gfsh commands</span> - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/tools_modules/gfsh/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/tools_modules/gfsh/chapter_overview.html.md.erb b/geode-docs/tools_modules/gfsh/chapter_overview.html.md.erb deleted file mode 100644 index 08218a6..0000000 --- a/geode-docs/tools_modules/gfsh/chapter_overview.html.md.erb +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: gfsh (Geode SHell) ---- - -Geode gfsh (pronounced "jee-fish") provides a single, powerful command-line interface from which you can launch, manage, and monitor Geode processes, data, and applications. - -- **[What You Can Do with gfsh](about_gfsh.html)** - - `gfsh` supports the administration, debugging, and deployment of Apache Geode processes and applications. - -- **[Starting gfsh](starting_gfsh.html)** - - Before you start gfsh, confirm that you have set JAVA\_HOME and that your PATH variable includes the gfsh executable. - -- **[Configuring the gfsh Environment](configuring_gfsh.html)** - - The `gfsh.bat` and `gfsh` bash script automatically append the required Apache Geode and JDK .jar libraries to your existing CLASSPATH. There are user-configurable properties you can set for security, environment variables, logging, and troubleshooting. - -- **[Useful gfsh Shell Variables](useful_gfsh_shell_variables.html)** - - You can use the built-in `gfsh` shell variables in scripts. - -- **[Basic Shell Features and Command-Line Usage](getting_started_gfsh.html)** - - The `gfsh` utility provides useful features for a shell environment, including command auto-complete, preserved command history, and delimiting of multi-line commands. Context-sensitive help is available by command and by topic. - -- **[TutorialâPerforming Common Tasks with gfsh](tour_of_gfsh.html)** - - This topic takes you through a typical sequence of tasks that you execute after starting `gfsh`. - -- **[Quick Reference of gfsh Commands by Functional Area](gfsh_quick_reference.html)** - - This quick reference sorts all commands into functional areas. - -- **[gfsh Command Help](gfsh_command_index.html)** - - This section provides help and usage information on all `gfsh` commands, listed alphabetically. - -- **[Creating and Running gfsh Command Scripts](command_scripting.html)** - - gfsh offers several ways to run commands in a scripting environment. - -- **[Running gfsh Commands on the OS Command Line](os_command_line_execution.html)** - -- **[Mapping of cache.xml Elements to gfsh Configuration Commands.](cache_xml_2_gfsh.html)** - - You can configure a Geode cluster using either cache.xml files, or you can use gfsh and the cluster configuration service to configure a cluster. This section maps cache.xml elements to the gfsh commands that configure and manage a cluster. - -
