You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by kl...@apache.org on 2017/03/01 00:14:30 UTC
[31/34] geode git commit: GEODE-2550 Improve README and BUILDING
GEODE-2550 Improve README and BUILDING
This closes #407
Project: http://git-wip-us.apache.org/repos/asf/geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/geode/commit/b5fd6b50
Tree: http://git-wip-us.apache.org/repos/asf/geode/tree/b5fd6b50
Diff: http://git-wip-us.apache.org/repos/asf/geode/diff/b5fd6b50
Branch: refs/heads/GEODE-4160-mockito
Commit: b5fd6b50b18ce13cb53ef72f9fe5f363cb566ba5
Parents: 712d87f
Author: Anthony Baker <ab...@apache.org>
Authored: Sat Feb 25 08:09:48 2017 -0800
Committer: Anthony Baker <ab...@apache.org>
Committed: Mon Feb 27 20:29:55 2017 -0800
----------------------------------------------------------------------
BUILDING.md | 68 ++++++-----------------
README.md | 162 +++++++++++++++++++++++++++++++++++++++++++------------
2 files changed, 144 insertions(+), 86 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/geode/blob/b5fd6b50/BUILDING.md
----------------------------------------------------------------------
diff --git a/BUILDING.md b/BUILDING.md
index 0c7bf4d..308ef8a 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -1,64 +1,30 @@
# Building this Release from Source
-Build instructions differ slightly for Unix and Windows platforms.
All platforms require a Java installation, with JDK 1.8 or more recent version.
-## Build from Source on Unix
+Set the JAVA\_HOME environment variable. For example:
-1. Set the JAVA\_HOME environment variable. For example:
+| Platform | Command |
+| :---: | --- |
+| Unix | ``export JAVA_HOME=/usr/java/jdk1.8.0_121`` |
+| OSX | ``export JAVA_HOME=`/usr/libexec/java_home -v 1.8`` |
+| Windows | ``set JAVA_HOME="C:\Program Files\Java\jdk1.8.0_121"`` |
- ```
- JAVA_HOME=/usr/java/jdk1.8.0_60
- export JAVA_HOME
- ```
-2. Download the project source from the Releases page at [Apache Geode] (http://geode.apache.org), and unpack the source code.
-3. Within the directory containing the unpacked source code, build without the tests:
-
- ```
- $ ./gradlew build -Dskip.tests=true
- ```
-Or, build with the tests:
-
- ```
- $ ./gradlew build
- ```
-The built binaries will be in `geode-assembly/build/distributions/`,
-or the `gfsh` script can be found in
-`geode-assembly/build/install/apache-geode/bin/`.
-4. Verify the installation by invoking `gfsh` to print version information and exit:
-
- ```
- $ gfsh version
- v1.1.0
- ```
+Download the project source from the Releases page at [Apache Geode]
+(http://geode.apache.org/releases/), and unpack the source code.
-## Build from Source on Windows
+Within the directory containing the unpacked source code, run the gradle build:
-1. Set the JAVA\_HOME environment variable. For example:
+ $ ./gradlew build
- ```
- $ set JAVA_HOME="C:\Program Files\Java\jdk1.8.0_60"
- ```
-2. Install Gradle, version 2.12 or a more recent version.
-3. Download the project source from the Releases page at [Apache Geode] (http://geode.apache.org), and unpack the source code.
-4. Within the folder containing the unpacked source code, build without the tests:
+Once the build completes, the project files will be installed at
+`geode-assembly/build/install/apache-geode`. The distribution archives will be
+created in `geode-assembly/build/distributions/`.
- ```
- $ gradle build -Dskip.test=true
- ```
-Or, build with the tests:
+Verify the installation by invoking the `gfsh` shell command to print version
+information:
- ```
- $ gradle build
- ```
-The built binaries will be in `geode-assembly\build\distributions\`,
-or the `gfsh.bat` script can be found in
-`geode-assembly\build\install\apache-geode\bin\`.
-4. Verify the installation by invoking `gfsh` to print version information and exit:
-
- ```
- $ gfsh.bat version
+ $ ./geode-assembly/build/install/apache-geode/bin/gfsh version
v1.1.0
- ```
-
+Note: on Windows invoke the `gfsh.bat` script to print the version string.
http://git-wip-us.apache.org/repos/asf/geode/blob/b5fd6b50/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 645f420..0909364 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,152 @@
[<img src="https://geode.apache.org/img/apache_geode_logo.png" align="center"/>](http://geode.apache.org)
-[](https://travis-ci.org/apache/geode) [](https://www.apache.org/licenses/LICENSE-2.0) [](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.geode%22)
+[](https://travis-ci.org/apache/geode) [](https://www.apache.org/licenses/LICENSE-2.0) [](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.geode%22) [](http://brewformulas.org/ApacheGeode) [](https://hub.docker.com/r/apachegeode/geode/)
+
## Contents
-1. [Overview](#overview)
+1. [Overview](#overview)
+2. [How to Get Apache Geode](#obtaining)
2. [Main Concepts and Components](#concepts)
3. [Location of Directions for Building from Source](#building)
4. [Geode in 5 minutes](#started)
5. [Application Development](#development)
6. [Documentation](http://geode.apache.org/docs/)
7. [Wiki](https://cwiki.apache.org/confluence/display/GEODE/Index)
-
-## <a name="overview"></a>Overview
-[Apache Geode](http://geode.apache.org/) is a data management platform that provides real-time, consistent access to data-intensive applications throughout widely distributed cloud architectures.
-Apache Geode pools memory, CPU, network resources, and optionally local disk across multiple processes to manage application objects and behavior. It uses dynamic replication and data partitioning techniques to implement high availability, improved performance, scalability, and fault tolerance. In addition to being a distributed data container, Apache Geode is an in-memory data management system that provides reliable asynchronous event notifications and guaranteed message delivery.
+## <a name="overview"></a>Overview
-Apache Geode is a mature, robust technology originally developed by GemStone Systems in Beaverton, Oregon. Commercially available as GemFire\u2122, the technology was first deployed in the financial sector as the transactional, low-latency data engine used in Wall Street trading platforms. Today Apache Geode is used by over 600 enterprise customers for high-scale business applications that must meet low latency and 24x7 availability requirements. An example deployment includes [China National Railways](http://pivotal.io/big-data/case-study/scaling-online-sales-for-the-largest-railway-in-the-world-china-railway-corporation) that uses Geode to run railway ticketing for the entire country of China with a 10 node cluster that manages 2 terabytes of "hot data" in memory, and 10 backup nodes for high availability and elastic scale.
+[Apache Geode](http://geode.apache.org/) is
+a data management platform that provides real-time, consistent access to
+data-intensive applications throughout widely distributed cloud architectures.
+
+Apache Geode pools memory, CPU, network resources, and optionally local disk
+across multiple processes to manage application objects and behavior. It uses
+dynamic replication and data partitioning techniques to implement high
+availability, improved performance, scalability, and fault tolerance. In
+addition to being a distributed data container, Apache Geode is an in-memory
+data management system that provides reliable asynchronous event notifications
+and guaranteed message delivery.
+
+Apache Geode is a mature, robust technology originally developed by GemStone
+Systems. Commercially available as GemFire\u2122, it was first deployed in the
+financial sector as the transactional, low-latency data engine used in Wall
+Street trading platforms. Today Apache Geode technology is used by hundreds of
+enterprise customers for high-scale business applications that must meet low
+latency and 24x7 availability requirements.
+
+## <a name="obtaining"></a>How to Get Apache Geode
+
+You can download Apache Geode from the
+[website](http://geode.apache.org/releases/), run a Docker
+[image](https://hub.docker.com/r/apachegeode/geode/), or install with
+[homebrew](http://brewformulas.org/ApacheGeode) on OSX. Application developers
+can load dependencies from [Maven
+Central](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.geode%22).
+
+Maven
+```
+<dependencies>
+ <dependency>
+ <groupId>org.apache.geode</groupId>
+ <artifactId>geode-core</artifactId>
+ <version>$VERSION</version>
+ </dependency>
+</dependencies>
+```
+
+Gradle
+```
+dependencies {
+ compile "org.apache.geode:geode-core:$VERSION"
+}
+```
## <a name="concepts"></a>Main Concepts and Components
-_Caches_ are an abstraction that describe a node in an Apache Geode distributed system.
+_Caches_ are an abstraction that describe a node in an Apache Geode distributed
+system.
-Within each cache, you define data _regions_. Data regions are analogous to tables in a relational database and manage data in a distributed fashion as name/value pairs. A _replicated_ region stores identical copies of the data on each cache member of a distributed system. A _partitioned_ region spreads the data among cache members. After the system is configured, client applications can access the distributed data in regions without knowledge of the underlying system architecture. You can define listeners to receive notifications when data has changed, and you can define expiration criteria to delete obsolete data in a region.
+Within each cache, you define data _regions_. Data regions are analogous to
+tables in a relational database and manage data in a distributed fashion as
+name/value pairs. A _replicated_ region stores identical copies of the data on
+each cache member of a distributed system. A _partitioned_ region spreads the
+data among cache members. After the system is configured, client applications
+can access the distributed data in regions without knowledge of the underlying
+system architecture. You can define listeners to receive notifications when
+data has changed, and you can define expiration criteria to delete obsolete
+data in a region.
-_Locators_ provide clients with both discovery and server load balancing services. Clients are configured with locator information, and the locators maintain a dynamic list of member servers. The locators provide clients with connection information to a server.
+_Locators_ provide clients with both discovery and server load balancing
+services. Clients are configured with locator information, and the locators
+maintain a dynamic list of member servers. The locators provide clients with
+connection information to a server.
Apache Geode includes the following features:
-* Combines redundancy, replication, and a "shared nothing" persistence architecture to deliver fail-safe reliability and performance.
-* Horizontally scalable to thousands of cache members, with multiple cache topologies to meet different enterprise needs. The cache can be distributed across multiple computers.
+* Combines redundancy, replication, and a "shared nothing" persistence
+ architecture to deliver fail-safe reliability and performance.
+* Horizontally scalable to thousands of cache members, with multiple cache
+ topologies to meet different enterprise needs. The cache can be
+ distributed across multiple computers.
* Asynchronous and synchronous cache update propagation.
-* Delta propagation distributes only the difference between old and new versions of an object (delta) instead of the entire object, resulting in significant distribution cost savings.
-* Reliable asynchronous event notifications and guaranteed message delivery through optimized, low latency distribution layer.
-* Applications run 4 to 40 times faster with no additional hardware.
-* Data awareness and real-time business intelligence. If data changes as you retrieve it, you see the changes immediately.
-* Integration with Spring Framework to speed and simplify the development of scalable, transactional enterprise applications.
+* Delta propagation distributes only the difference between old and new
+ versions of an object (delta) instead of the entire object, resulting in
+ significant distribution cost savings.
+* Reliable asynchronous event notifications and guaranteed message delivery
+ through optimized, low latency distribution layer.
+* Data awareness and real-time business intelligence. If data changes as
+ you retrieve it, you see the changes immediately.
+* Integration with Spring Framework to speed and simplify the development
+ of scalable, transactional enterprise applications.
* JTA compliant transaction support.
-* Cluster-wide configurations that can be persisted and exported to other clusters.
+* Cluster-wide configurations that can be persisted and exported to other
+ clusters.
* Remote cluster management through HTTP.
* REST APIs for REST-enabled application development.
-* Rolling upgrades may be possible, but they will be subject to any limitations imposed by new features.
+* Rolling upgrades may be possible, but they will be subject to any
+ limitations imposed by new features.
## <a name="building"></a>Building this Release from Source
-Directions to build Apache Geode from source are in the source distribution, file `BUILDING.md`.
+See [BUILDING.md](https://github.com/apache/geode/blob/develop/BUILDING.md) for
+instructions on how to build the project.
## <a name="started"></a>Geode in 5 minutes
-With a JDK version 1.8 or a more recent version installed,
+Geode requires installation of JDK version 1.8. After installing Apache Geode,
start a locator and server:
$ gfsh
- gfsh> start locator --name=locator
- gfsh> start server --name=server
+ gfsh> start locator
+ gfsh> start server
Create a region:
- gfsh> create region --name=region --type=REPLICATE
+ gfsh> create region --name=hello --type=REPLICATE
+
+Write a client application (this example uses a [Gradle](https://gradle.org)
+build script):
+
+_build.gradle_
-Write a client application:
+ apply plugin: 'java'
+ apply plugin: 'application'
-_HelloWorld.java_
+ mainClassName = 'HelloWorld'
+
+ repositories { mavenCentral() }
+ dependencies {
+ compile 'org.apache.geode:geode-core:1.1.0'
+ runtime 'org.slf4j:slf4j-log4j12:1.7.24'
+ }
+
+_src/main/java/HelloWorld.java_
import java.util.Map;
import org.apache.geode.cache.Region;
import org.apache.geode.cache.client.*;
-
+
public class HelloWorld {
public static void main(String[] args) throws Exception {
ClientCache cache = new ClientCacheFactory()
@@ -75,11 +154,11 @@ _HelloWorld.java_
.create();
Region<String, String> region = cache
.<String, String>createClientRegionFactory(ClientRegionShortcut.CACHING_PROXY)
- .create("region");
-
+ .create("hello");
+
region.put("1", "Hello");
region.put("2", "World");
-
+
for (Map.Entry<String, String> entry : region.entrySet()) {
System.out.format("key = %s, value = %s\n", entry.getKey(), entry.getValue());
}
@@ -87,16 +166,30 @@ _HelloWorld.java_
}
}
-Compile and run `HelloWorld.java`. The classpath should include `geode-dependencies.jar`.
+Build and run the `HelloWorld` example:
+
+ $ gradle run
+
+The application will connect to the running cluster, create a local cache, put
+some data in the cache, and print the cached data to the console:
- javac -cp /some/path/geode/geode-assembly/build/install/apache-geode/lib/geode-dependencies.jar HelloWorld.java
- java -cp .:/some/path/geode/geode-assembly/build/install/apache-geode/lib/geode-dependencies.jar HelloWorld
+ key = 1, value = Hello
+ key = 2, value = World
+
+Finally, shutdown the Geode server and locator:
+
+ $ gfsh> shutdown --include-locators=true
+
+For more information see the [Geode
+Examples](https://github.com/apache/geode-examples) repository or the
+[documentation](http://geode.apache.org/docs/).
## <a name="development"></a>Application Development
Apache Geode applications can be written in these client technologies:
-* Java [client](http://geode.apache.org/docs/guide/topologies_and_comm/cs_configuration/chapter_overview.html) or [peer](http://geode.apache.org/docs/guide/topologies_and_comm/p2p_configuration/chapter_overview.html)
+* Java [client](http://geode.apache.org/docs/guide/topologies_and_comm/cs_configuration/chapter_overview.html)
+ or [peer](http://geode.apache.org/docs/guide/topologies_and_comm/p2p_configuration/chapter_overview.html)
* [REST](http://geode.apache.org/docs/guide/rest_apps/chapter_overview.html)
* [Memcached](https://cwiki.apache.org/confluence/display/GEODE/Moving+from+memcached+to+gemcached)
* [Redis](https://cwiki.apache.org/confluence/display/GEODE/Geode+Redis+Adapter)
@@ -106,4 +199,3 @@ The following libraries are available external to the Apache Geode project:
* [Spring Data GemFire](http://projects.spring.io/spring-data-gemfire/)
* [Spring Cache](http://docs.spring.io/spring/docs/current/spring-framework-reference/html/cache.html)
* [Python](https://github.com/gemfire/py-gemfire-rest)
-