├── .gitignore
├── pom.xml
├── src
    ├── test
    │   └── java
    │   │   └── com
    │   │       └── cscotta
    │   │           └── recordinality
    │   │               └── RecordinalityTest.java
    └── main
    │   └── java
    │       └── com
    │           └── cscotta
    │               └── recordinality
    │                   └── Recordinality.java
├── README.md
└── LICENSE


/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | *.iml
3 | .idea/
4 | target/
5 | *.class


--------------------------------------------------------------------------------
/pom.xml:
--------------------------------------------------------------------------------
  1 | <?xml version="1.0"?>
  2 | <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  3 |   <modelVersion>4.0.0</modelVersion>
  4 |   <groupId>com.cscotta</groupId>
  5 |   <artifactId>recordinality</artifactId>
  6 |   <version>0.1</version>
  7 |   <name>recordinality</name>
  8 |   <url>https://www.github.com/cscotta/recordinality</url>
  9 |   <packaging>jar</packaging>
 10 |   <dependencies>
 11 |     <dependency>
 12 |       <groupId>com.google.guava</groupId>
 13 |       <artifactId>guava</artifactId>
 14 |       <version>12.0</version>
 15 |     </dependency>
 16 |     <dependency>
 17 |       <groupId>org.apache.commons</groupId>
 18 |       <artifactId>commons-math3</artifactId>
 19 |       <version>3.0</version>
 20 |     </dependency>
 21 |     <dependency>
 22 |       <groupId>junit</groupId>
 23 |       <artifactId>junit</artifactId>
 24 |       <version>4.8.2</version>
 25 |       <scope>test</scope>
 26 |     </dependency>
 27 |     <dependency>
 28 |       <groupId>commons-io</groupId>
 29 |       <artifactId>commons-io</artifactId>
 30 |       <version>2.1</version>
 31 |     </dependency>
 32 |   </dependencies>
 33 |   <build>
 34 |     <sourceDirectory>src/main/java</sourceDirectory>
 35 |     <testSourceDirectory>src/test/java</testSourceDirectory>
 36 |     <plugins>
 37 |       <plugin>
 38 |         <groupId>org.apache.maven.plugins</groupId>
 39 |         <artifactId>maven-compiler-plugin</artifactId>
 40 |         <version>2.3.2</version>
 41 |         <configuration>
 42 |           <source>1.6</source>
 43 |           <target>1.6</target>
 44 |         </configuration>
 45 |       </plugin>
 46 |       <plugin>
 47 |         <groupId>org.apache.maven.plugins</groupId>
 48 |         <artifactId>maven-surefire-plugin</artifactId>
 49 |         <version>2.8.1</version>
 50 |         <configuration>
 51 |           <useFile>false</useFile>
 52 |           <useSystemClassLoader>false</useSystemClassLoader>
 53 |           <argLine>-Xmx512m</argLine>
 54 |           <includes>
 55 |             <exclude>**/*Test.java</exclude>
 56 |             <include>**/*Spec.java</include>
 57 |           </includes>
 58 |           <excludes>
 59 |           </excludes>
 60 |         </configuration>
 61 |       </plugin>
 62 |       <plugin>
 63 |         <groupId>org.apache.maven.plugins</groupId>
 64 |         <artifactId>maven-shade-plugin</artifactId>
 65 |         <version>1.4</version>
 66 |         <executions>
 67 |           <execution>
 68 |             <phase>package</phase>
 69 |             <goals>
 70 |               <goal>shade</goal>
 71 |             </goals>
 72 |             <configuration>
 73 |               <transformers>
 74 |                 <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
 75 |               </transformers>
 76 |               <filters>
 77 |                 <filter>
 78 |                   <artifact>*:*</artifact>
 79 |                   <excludes>
 80 |                     <exclude>META-INF/*.SF</exclude>
 81 |                     <exclude>META-INF/*.DSA</exclude>
 82 |                     <exclude>META-INF/*.RSA</exclude>
 83 |                   </excludes>
 84 |                 </filter>
 85 |               </filters>
 86 |               <artifactSet>
 87 |                 <excludes>
 88 |                   <exclude>junit:junit</exclude>
 89 |                 </excludes>
 90 |               </artifactSet>
 91 |             </configuration>
 92 |           </execution>
 93 |         </executions>
 94 |       </plugin>
 95 |       <plugin>
 96 |         <groupId>org.apache.maven.plugins</groupId>
 97 |         <artifactId>maven-source-plugin</artifactId>
 98 |         <version>2.1.2</version>
 99 |         <executions>
100 |           <execution>
101 |             <id>attach-sources</id>
102 |             <phase>package</phase>
103 |             <goals>
104 |               <goal>jar-no-fork</goal>
105 |             </goals>
106 |           </execution>
107 |         </executions>
108 |       </plugin>
109 |     </plugins>
110 |   </build>
111 |   <repositories>
112 |     <repository>
113 |       <id>central</id>
114 |       <name>Maven repository</name>
115 |       <url>http://repo1.maven.org/maven2</url>
116 |     </repository>
117 |   </repositories>
118 | </project>
119 | 


--------------------------------------------------------------------------------
/src/test/java/com/cscotta/recordinality/RecordinalityTest.java:
--------------------------------------------------------------------------------
 1 | package com.cscotta.recordinality;
 2 | 
 3 | import java.io.File;
 4 | import java.net.URI;
 5 | import java.util.HashSet;
 6 | import java.util.List;
 7 | import java.util.Set;
 8 | import java.util.concurrent.*;
 9 | 
10 | import org.junit.Test;
11 | import static org.junit.Assert.assertTrue;
12 | import com.google.common.collect.Lists;
13 | import org.apache.commons.math3.stat.descriptive.moment.Mean;
14 | import org.apache.commons.math3.stat.descriptive.moment.StandardDeviation;
15 | import org.apache.commons.io.FileUtils;
16 | 
17 | public class RecordinalityTest {
18 | 
19 |     @Test
20 |     public void testRecordinality() throws Exception {
21 |         final int numRuns = 10000;
22 |         final int[] kSizes = new int[]{4,8,16,32,64,128,256,512};
23 | 
24 |         // Build our lowercased, trimmed list of words from our source file.
25 |         final String msnd = "/midsummer-nights-dream-gutenberg.txt";
26 |         final URI uri = getClass().getResource(msnd).toURI();
27 |         final List<String> input = FileUtils.readLines(new File(uri));
28 |         final List<String> words = Lists.newArrayList();
29 |         for (String line : input) words.add(line.trim().toLowerCase());
30 | 
31 |         // Compute the actual cardinality of our set.
32 |         final Set<String> actualSet = new HashSet<String>();
33 |         for (String line : words) actualSet.add(line);
34 |         final double actualSize = actualSet.size();
35 |         System.out.println("Actual cardinality: " + actualSet.size());
36 | 
37 |         // Run 'recordinality' repeatedly over the stream.
38 |         final ExecutorService exec = Executors.newFixedThreadPool(
39 |             Runtime.getRuntime().availableProcessors());
40 | 
41 |         final List<Future<Result>> resultFutures = Lists.newArrayList();
42 |         for (int kSize : kSizes) {
43 |             resultFutures.add(exec.submit(buildRun(kSize, numRuns, words)));
44 |         }
45 | 
46 |         final double[] errorBounds = new double[]{2.5, 1, 0.6, 0.4, 0.25, 0.2, 0.1, 0.05};
47 |         int errorBoundIdx = 0;
48 |         for (Future<Result> future : resultFutures) {
49 |             Result result = future.get();
50 |             System.out.println("k-size: " + result.kSize);
51 |             System.out.println("Mean est: " + result.mean);
52 |             System.out.println("Std. err: " + result.stdError);
53 |             System.out.println("Mean run time: " + (result.runTime / numRuns) + "ms.");
54 |             System.out.println("Mean estimate is off by a factor of " + ((result.mean / actualSize) - 1));
55 |             System.out.println("\n==================================================\n");
56 |             assertTrue(result.stdError <= errorBounds[errorBoundIdx]);
57 |             errorBoundIdx += 1;
58 |         }
59 | 
60 |         exec.shutdown();
61 |     }
62 | 
63 |         private Callable<Result> buildRun(final int kSize, final int numRuns,
64 |                                           final List<String> lines) {
65 |             return new Callable<Result>() {
66 |                 public Result call() throws Exception {
67 |                     long start = System.currentTimeMillis();
68 |                     final double[] results = new double[numRuns];
69 |                     for (int i = 0; i < numRuns; i++) {
70 |                         Recordinality rec = new Recordinality(kSize);
71 |                         for (String line : lines) rec.observe(line);
72 |                         results[i] = rec.estimateCardinality();
73 |                     }
74 |                     double mean = new Mean().evaluate(results);
75 |                     double stdDev = new StandardDeviation().evaluate(results);
76 |                     double stdError = stdDev / 3193;
77 |                     long runTime = System.currentTimeMillis() - start;
78 |                     return new Result(kSize, mean, stdError, runTime);
79 |                 }
80 |             };
81 |         }
82 | 
83 | 
84 |     private static final class Result {
85 |         int kSize;
86 |         double mean;
87 |         double stdError;
88 |         long runTime;
89 | 
90 |         public Result(int kSize, double mean, double stdError, long runTime) {
91 |             this.kSize = kSize;
92 |             this.mean = mean;
93 |             this.stdError = stdError;
94 |             this.runTime = runTime;
95 |         }
96 |     }
97 | 
98 | }
99 | 


--------------------------------------------------------------------------------
/src/main/java/com/cscotta/recordinality/Recordinality.java:
--------------------------------------------------------------------------------
  1 | /*
  2 |  * Copyright 2013, C. Scott Andreas (@cscotta / scott@paradoxica.net)
  3 |  *
  4 |  * Licensed under the Apache License, Version 2.0 (the "License");
  5 |  * you may not use this file except in compliance with the License.
  6 |  * You may obtain a copy of the License at
  7 |  *
  8 |  *     http://www.apache.org/licenses/LICENSE-2.0
  9 |  *
 10 |  * Unless required by applicable law or agreed to in writing, software
 11 |  * distributed under the License is distributed on an "AS IS" BASIS,
 12 |  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 |  * See the License for the specific language governing permissions and
 14 |  * limitations under the License.
 15 | */
 16 | 
 17 | package com.cscotta.recordinality;
 18 | 
 19 | import java.util.Set;
 20 | import java.util.Random;
 21 | import java.util.concurrent.ConcurrentSkipListMap;
 22 | import java.util.concurrent.atomic.AtomicLong;
 23 | 
 24 | import com.google.common.hash.Hashing;
 25 | import com.google.common.hash.HashFunction;
 26 | import com.google.common.collect.ImmutableSet;
 27 | 
 28 | public class Recordinality {
 29 | 
 30 |     private final int sampleSize;
 31 |     private final int seed = new Random().nextInt();
 32 |     private final HashFunction hash = Hashing.murmur3_128(seed);
 33 |     private final AtomicLong modifications = new AtomicLong(0);
 34 |     private final AtomicLong cachedMin = new AtomicLong(Long.MIN_VALUE);
 35 |     private final ConcurrentSkipListMap<Long, Element> kMap =
 36 |         new ConcurrentSkipListMap<Long, Element>();
 37 |     private volatile int kMapSize = 0;
 38 | 
 39 |     /*
 40 |      * Initializes a new Recordinality instance with a configurable 'k'-size.
 41 |      */
 42 |     public Recordinality(int sampleSize) {
 43 |         this.sampleSize = sampleSize;
 44 |     }
 45 | 
 46 |     /*
 47 |      * Observes a value in a stream.
 48 |      */
 49 |     public void observe(String element) {
 50 |         boolean inserted = insertIfFits(element);
 51 |         if (inserted) modifications.incrementAndGet();
 52 |     }
 53 | 
 54 |     /*
 55 |      * Returns an estimate of the stream's cardinality. For a description
 56 |      * of this estimator, see see §2 Theorem 1 in the Recordinality paper:
 57 |      * http://www-apr.lip6.fr/~lumbroso/Publications/HeLuMaVi12.pdf
 58 |      */
 59 |     public long estimateCardinality() {
 60 |         long pow = modifications.get() - sampleSize + 1;
 61 |         double estimate = (sampleSize * (Math.pow(1 + (1.0 / sampleSize), pow))) - 1;
 62 |         return (long) estimate;
 63 |     }
 64 | 
 65 |     /*
 66 |      * Returns an estimate of Recordinality's error for this stream,
 67 |      * expressed in terms of standard error. For a description of this estimator,
 68 |      * see §2 Theorem 2: http://www-apr.lip6.fr/~lumbroso/Publications/HeLuMaVi12.pdf
 69 |      */
 70 |     public double estimateError() {
 71 |         double estCardinality = estimateCardinality();
 72 |         double error = Math.sqrt(Math.pow(
 73 |                 (estCardinality / (sampleSize * Math.E)), (1.0 / sampleSize)) - 1);
 74 |         return error;
 75 |     }
 76 | 
 77 |     /*
 78 |      * Returns the current set of k-records observed in the stream.
 79 |      */
 80 |     public Set<Element> getSample() {
 81 |         return ImmutableSet.copyOf(kMap.values());
 82 |     }
 83 | 
 84 |     /*
 85 |      * Inserts a record into our k-set if it fits.
 86 |     */
 87 |     private boolean insertIfFits(String element) {
 88 |         long hashedValue = hash.hashString(element).asLong();
 89 | 
 90 |         // Short-circuit if our k-set is saturated. Common case.
 91 |         if (hashedValue < cachedMin.get() && kMapSize >= sampleSize)
 92 |             return false;
 93 | 
 94 |         synchronized (this) {
 95 |             assert(kMapSize <= sampleSize);
 96 | 
 97 |             if (kMapSize < sampleSize || hashedValue >= cachedMin.get()) {
 98 |                 Element existing = kMap.get(hashedValue);
 99 |                 if (existing != null) {
100 |                     existing.count.incrementAndGet();
101 |                     return false;
102 |                 } else {
103 |                     long lowestKey = (kMapSize > 0) ? kMap.firstKey() : Long.MIN_VALUE;
104 |                     if (hashedValue > lowestKey || kMapSize < sampleSize) {
105 |                         kMap.put(hashedValue, new Element(element));
106 |                         kMapSize++;
107 |                         cachedMin.set(lowestKey);
108 |                         if (kMapSize > sampleSize) {
109 |                             kMap.remove(lowestKey);
110 |                             kMapSize = sampleSize;
111 |                         }
112 |                         return true;
113 |                     } else {
114 |                         return false;
115 |                     }
116 |                 }
117 |             }
118 | 
119 |             return false;
120 |         }
121 |     }
122 | 
123 |     @Override
124 |     public String toString() {
125 |         synchronized (this) {
126 |             return "Recordinality{" +
127 |                     "sampleSize=" + sampleSize +
128 |                     ", hash=" + hash +
129 |                     ", modifications=" + modifications.get() +
130 |                     ", cachedMin=" + cachedMin.get() +
131 |                     ", mapSize=" + kMap.size() +
132 |                     ", estCardinality=" + estimateCardinality() +
133 |                     ", estError=" + estimateError() +
134 |                     '}';
135 |         }
136 |     }
137 | 
138 |     /*
139 |      * Inner class representing a pair of an observed k-record in the stream
140 |      * along with the number of times it has been observed.
141 |      */
142 |     public class Element {
143 | 
144 |         public final String value;
145 |         public final AtomicLong count;
146 | 
147 |         public Element(String value) {
148 |             this.value = value;
149 |             this.count = new AtomicLong(1);
150 |         }
151 | 
152 |         @Override
153 |         public String toString() {
154 |             return "Element{" +
155 |                     "value='" + value + '\'' +
156 |                     ", count=" + count +
157 |                     '}';
158 |         }
159 |     }
160 | 
161 | }
162 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | #### Cardinality Estimation and Distinct Value Sampling with Recordinality
 2 | ###### C. Scott Andreas | Aug 19, 2013
 3 | 
 4 | **Cardinality Estimation**
 5 | 
 6 | Determining the number of unique elements that make up a stream is a frequently-encountered problem in stream processing. A few applications include counting the number of unique visitors to a website or determining the number of unique hosts communicating with an application cluster. In both cases, the number can be arbitrarily large, making it infeasible to maintain a map containing each unique value and just counting the elements. Instead, we turn to a category of algorithms called "[sketches](http://blog.aggregateknowledge.com/2011/09/13/streaming-algorithms-and-sketches/)." Sketches help us estimate the cardinality of infinite streams using very little memory and with bounded error estimates.
 7 | 
 8 | [HyperLogLog](http://blog.aggregateknowledge.com/2012/10/25/sketch-of-the-day-hyperloglog-cornerstone-of-a-big-data-infrastructure/) is an excellent choice for streaming cardinality estimation in most cases. However, HLL is simply an estimator - it is a tool that does one thing, and one thing very well. At Aggregate Knowledge's May SketchConf, Jérémie Lumbroso introduced me to another lesser-known sketch called "Recordinality." Here is [the paper](http://www-apr.lip6.fr/~lumbroso/Publications/HeLuMaVi12.pdf) describing it.
 9 | 
10 | **Recordinality**
11 | 
12 | Recordinality is unique in that it provides cardinality estimation like HLL, but also offers "distinct value sampling." This means that Recordinality can allow us to fetch a random sample of distinct elements in a stream, invariant to repetition. Put more succinctly, given a stream of elements containing 1,000,000 occurrences of 'A' and one occurrence each of 'B' - 'Z', the probability of any letter appearing in our sample is equal. Moreover, we can also efficiently store the number of times elements in our distinct sample have been observed. This can help us to understand the distribution of occurrences of elements in our stream. With it, we can answer questions like "do the elements we've sampled present in a power law-like pattern, or is the distribution of occurrences relatively even across the set?"
13 | 
14 | **The Algorithm**
15 | 
16 | Beyond these unique properties, Recordinality is especially interesting due to its simplicity. Here's how it works:
17 | 
18 |   1. Initialize a set of size k (the size of this set determines the accuracy of our estimates)
19 |   2. Compute the hash of each incoming element in the stream using a hash function such as [MurmurHash3](https://sites.google.com/site/murmurhash/).
20 |   3. If the k-set is not full, insert the hash value. If the set is full, determine if the value of the hash is greater than the lowest hash currently in the set. If so, replace it. If not, ignore it.
21 |   4. Each time we add or replace an element in the k-set, increment a counter.
22 | 
23 | The premise is straightforward: the cardinality of a stream can be estimated by hashing each element to a random value and counting the number of times a set containing the max of these values is mutated. We gain unique sampling if we switch from a set to a map and store the original value in our k-set. We gain counts of unique values observed by storing both the original value and incrementing a counter each time it's observed. In addition to being easy to reason about, it's also extraordinarily efficient. The common case requires only hashing an element and comparing two integers.
24 | 
25 | **Implementing Recordinality**
26 | 
27 | Interest piqued, Jérémie challenged me over dinner to implement it. Armed with Timon's advice on "[how to implement a paper](http://taco.cat/files/Screen%20Shot%202013-08-19%20at%202.58.36%20PM-N2VAMCNBev.png)" ([slides](https://docs.google.com/presentation/d/12mMdn5cjA-MhrbJSP6ThjIAs-YACWJ1p6BeSTXW0P4Q/edit?usp=sharing)), I read and re-read it making notes. A Saturday morning found me at [Sightglass](https://sightglasscoffee.com/) sitting down with the paper, a cup of Blueboon, and my laptop to begin implementation. One cup and a couple bugs later, I arrived at a working implementation of Recordinality and shuffled home to verify my results against those claimed by the paper against a known input set, which matched.
28 | 
29 | Here's an implementation of Recordinality in Java, comments added:
30 | https://github.com/cscotta/recordinality/blob/master/src/main/java/com/cscotta/recordinality/Recordinality.java
31 | 
32 | This implementation is both threadsafe and lockless in the common case, allowing all mutators and readers safe concurrent access without synchronization. If cardinality estimation with distinct value sampling is of interest to you, please consider this implementation as a starting point. Translations to other languages should be straightforward; please let me know if you attempt one and I'll list it here.
33 | 
34 | 
35 | **Performance**
36 | 
37 | The Recordinality paper includes mean cardinality and error estimates for k-values from 4 to 512 against a publicly-available dataset – namely, the text of A Midsummer Night's Dream. Here is a comparison of the results included in the paper versus those emitted by the unit test included with this implementation. The values recorded below are the results of 10,000 runs.
38 | 
39 | [Note: The source text used in the paper is listed as containing 3031 distinct words. The copy I've obtained for verification and based implementation stats on below from Project Gutenberg contained 3193 distinct words. It is included in this repository.]
40 | 
41 | | Size | Paper Mean (Expected: 3031) | Paper Error | Impl Mean (Expected: 3193) | Impl Error | Mean Run Time |
42 | |--------|---------------------------|-------------|----------------------------|------------|---------------|
43 | | 4      | 2737 | 1.04 | 3154 | 1.63 | 3ms   |
44 | | 8      | 2811 | 0.73 | 3187 | 0.91 | 3ms   |
45 | | 16     | 3040 | 0.54 | 3202 | 0.55 | 3ms   |
46 | | 32     | 3010 | 0.34 | 3179 | 0.34 | 3ms   |
47 | | 64     | 3020 | 0.22 | 3197 | 0.22 | 3ms   |
48 | | 128    | 3042 | 0.14 | 3193 | 0.13 | 4ms   |
49 | | 256    | 3044 | 0.08 | 3191 | 0.08 | 4ms   |
50 | | 512    | 3043 | 0.04 | 3192 | 0.04 | 4ms  |
51 | 
52 | You can run this test yourself by cloning the repo and typing `mvn test`. Here is an example of the expected output: https://gist.github.com/pkwarren/6275129
53 | 
54 | **Epilogue**
55 | 
56 | The implementation of Recordinality was driven by practical needs as much as it was by a desire to encourage greater cross-pollination between industry and academia. This is the first known open source implementation of this algorithm I'm aware of, and the only cardinality estimation sketch that provides distinct value sampling and the frequency of each. Working with Jérémie to understand and implement Recordinality was a pleasure (as most evenings talking shop that end at 2 am at Pilsner Inn are)! It's always a delight to see unique and useful algorithms spawn open source implementations for use by others coming after.
57 | 
58 | Thanks, Jérémie!
59 | 
60 | ---
61 | 
62 | Here are the [slides](https://speakerdeck.com/timonk/philippe-flajolets-contribution-to-streaming-algorithms) presented by Jérémie, along with a [video of the original presentation](http://www.youtube.com/watch?v=Xigaf8npHoI).
63 | 
64 | **Update:** Thanks to Philip Warren (@pkwarren) for catching a check against CSLM.size() that should have been short-circuited by a call to cachedMin.get() in the common case. Updated run time stats and performance above following this change. A few more similar changes will follow shortly.
65 | 
66 | **Update 2:** A much bigger thanks to Philip for [this commit](https://github.com/cscotta/recordinality/commit/a5579fa6909ee0746d4da9da0efcd6b924a260cc), which removes the use of CSLM.size() entirely. Previously, this implementation's time complexity varied with the size of the k-map. This commit eliminates this covariance. The initial version of this test took a mean of 116ms per run at k-512. Philip's changes bring it down to 4ms.
67 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 | Apache License
  2 | Version 2.0, January 2004
  3 | http://www.apache.org/licenses/
  4 | 
  5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  6 | 
  7 | 1. Definitions.
  8 | 
  9 | "License" shall mean the terms and conditions for use, reproduction, and
 10 | distribution as defined by Sections 1 through 9 of this document.
 11 | 
 12 | "Licensor" shall mean the copyright owner or entity authorized by the copyright
 13 | owner that is granting the License.
 14 | 
 15 | "Legal Entity" shall mean the union of the acting entity and all other entities
 16 | that control, are controlled by, or are under common control with that entity.
 17 | For the purposes of this definition, "control" means (i) the power, direct or
 18 | indirect, to cause the direction or management of such entity, whether by
 19 | contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
 20 | outstanding shares, or (iii) beneficial ownership of such entity.
 21 | 
 22 | "You" (or "Your") shall mean an individual or Legal Entity exercising
 23 | permissions granted by this License.
 24 | 
 25 | "Source" form shall mean the preferred form for making modifications, including
 26 | but not limited to software source code, documentation source, and configuration
 27 | files.
 28 | 
 29 | "Object" form shall mean any form resulting from mechanical transformation or
 30 | translation of a Source form, including but not limited to compiled object code,
 31 | generated documentation, and conversions to other media types.
 32 | 
 33 | "Work" shall mean the work of authorship, whether in Source or Object form, made
 34 | available under the License, as indicated by a copyright notice that is included
 35 | in or attached to the work (an example is provided in the Appendix below).
 36 | 
 37 | "Derivative Works" shall mean any work, whether in Source or Object form, that
 38 | is based on (or derived from) the Work and for which the editorial revisions,
 39 | annotations, elaborations, or other modifications represent, as a whole, an
 40 | original work of authorship. For the purposes of this License, Derivative Works
 41 | shall not include works that remain separable from, or merely link (or bind by
 42 | name) to the interfaces of, the Work and Derivative Works thereof.
 43 | 
 44 | "Contribution" shall mean any work of authorship, including the original version
 45 | of the Work and any modifications or additions to that Work or Derivative Works
 46 | thereof, that is intentionally submitted to Licensor for inclusion in the Work
 47 | by the copyright owner or by an individual or Legal Entity authorized to submit
 48 | on behalf of the copyright owner. For the purposes of this definition,
 49 | "submitted" means any form of electronic, verbal, or written communication sent
 50 | to the Licensor or its representatives, including but not limited to
 51 | communication on electronic mailing lists, source code control systems, and
 52 | issue tracking systems that are managed by, or on behalf of, the Licensor for
 53 | the purpose of discussing and improving the Work, but excluding communication
 54 | that is conspicuously marked or otherwise designated in writing by the copyright
 55 | owner as "Not a Contribution."
 56 | 
 57 | "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
 58 | of whom a Contribution has been received by Licensor and subsequently
 59 | incorporated within the Work.
 60 | 
 61 | 2. Grant of Copyright License.
 62 | 
 63 | Subject to the terms and conditions of this License, each Contributor hereby
 64 | grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
 65 | irrevocable copyright license to reproduce, prepare Derivative Works of,
 66 | publicly display, publicly perform, sublicense, and distribute the Work and such
 67 | Derivative Works in Source or Object form.
 68 | 
 69 | 3. Grant of Patent License.
 70 | 
 71 | Subject to the terms and conditions of this License, each Contributor hereby
 72 | grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
 73 | irrevocable (except as stated in this section) patent license to make, have
 74 | made, use, offer to sell, sell, import, and otherwise transfer the Work, where
 75 | such license applies only to those patent claims licensable by such Contributor
 76 | that are necessarily infringed by their Contribution(s) alone or by combination
 77 | of their Contribution(s) with the Work to which such Contribution(s) was
 78 | submitted. If You institute patent litigation against any entity (including a
 79 | cross-claim or counterclaim in a lawsuit) alleging that the Work or a
 80 | Contribution incorporated within the Work constitutes direct or contributory
 81 | patent infringement, then any patent licenses granted to You under this License
 82 | for that Work shall terminate as of the date such litigation is filed.
 83 | 
 84 | 4. Redistribution.
 85 | 
 86 | You may reproduce and distribute copies of the Work or Derivative Works thereof
 87 | in any medium, with or without modifications, and in Source or Object form,
 88 | provided that You meet the following conditions:
 89 | 
 90 | You must give any other recipients of the Work or Derivative Works a copy of
 91 | this License; and
 92 | You must cause any modified files to carry prominent notices stating that You
 93 | changed the files; and
 94 | You must retain, in the Source form of any Derivative Works that You distribute,
 95 | all copyright, patent, trademark, and attribution notices from the Source form
 96 | of the Work, excluding those notices that do not pertain to any part of the
 97 | Derivative Works; and
 98 | If the Work includes a "NOTICE" text file as part of its distribution, then any
 99 | Derivative Works that You distribute must include a readable copy of the
100 | attribution notices contained within such NOTICE file, excluding those notices
101 | that do not pertain to any part of the Derivative Works, in at least one of the
102 | following places: within a NOTICE text file distributed as part of the
103 | Derivative Works; within the Source form or documentation, if provided along
104 | with the Derivative Works; or, within a display generated by the Derivative
105 | Works, if and wherever such third-party notices normally appear. The contents of
106 | the NOTICE file are for informational purposes only and do not modify the
107 | License. You may add Your own attribution notices within Derivative Works that
108 | You distribute, alongside or as an addendum to the NOTICE text from the Work,
109 | provided that such additional attribution notices cannot be construed as
110 | modifying the License.
111 | You may add Your own copyright statement to Your modifications and may provide
112 | additional or different license terms and conditions for use, reproduction, or
113 | distribution of Your modifications, or for any such Derivative Works as a whole,
114 | provided Your use, reproduction, and distribution of the Work otherwise complies
115 | with the conditions stated in this License.
116 | 
117 | 5. Submission of Contributions.
118 | 
119 | Unless You explicitly state otherwise, any Contribution intentionally submitted
120 | for inclusion in the Work by You to the Licensor shall be under the terms and
121 | conditions of this License, without any additional terms or conditions.
122 | Notwithstanding the above, nothing herein shall supersede or modify the terms of
123 | any separate license agreement you may have executed with Licensor regarding
124 | such Contributions.
125 | 
126 | 6. Trademarks.
127 | 
128 | This License does not grant permission to use the trade names, trademarks,
129 | service marks, or product names of the Licensor, except as required for
130 | reasonable and customary use in describing the origin of the Work and
131 | reproducing the content of the NOTICE file.
132 | 
133 | 7. Disclaimer of Warranty.
134 | 
135 | Unless required by applicable law or agreed to in writing, Licensor provides the
136 | Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
137 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
138 | including, without limitation, any warranties or conditions of TITLE,
139 | NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
140 | solely responsible for determining the appropriateness of using or
141 | redistributing the Work and assume any risks associated with Your exercise of
142 | permissions under this License.
143 | 
144 | 8. Limitation of Liability.
145 | 
146 | In no event and under no legal theory, whether in tort (including negligence),
147 | contract, or otherwise, unless required by applicable law (such as deliberate
148 | and grossly negligent acts) or agreed to in writing, shall any Contributor be
149 | liable to You for damages, including any direct, indirect, special, incidental,
150 | or consequential damages of any character arising as a result of this License or
151 | out of the use or inability to use the Work (including but not limited to
152 | damages for loss of goodwill, work stoppage, computer failure or malfunction, or
153 | any and all other commercial damages or losses), even if such Contributor has
154 | been advised of the possibility of such damages.
155 | 
156 | 9. Accepting Warranty or Additional Liability.
157 | 
158 | While redistributing the Work or Derivative Works thereof, You may choose to
159 | offer, and charge a fee for, acceptance of support, warranty, indemnity, or
160 | other liability obligations and/or rights consistent with this License. However,
161 | in accepting such obligations, You may act only on Your own behalf and on Your
162 | sole responsibility, not on behalf of any other Contributor, and only if You
163 | agree to indemnify, defend, and hold each Contributor harmless for any liability
164 | incurred by, or claims asserted against, such Contributor by reason of your
165 | accepting any such warranty or additional liability.
166 | 
167 | END OF TERMS AND CONDITIONS
168 | 
169 | APPENDIX: How to apply the Apache License to your work
170 | 
171 | To apply the Apache License to your work, attach the following boilerplate
172 | notice, with the fields enclosed by brackets "[]" replaced with your own
173 | identifying information. (Don't include the brackets!) The text should be
174 | enclosed in the appropriate comment syntax for the file format. We also
175 | recommend that a file or class name and description of purpose be included on
176 | the same "printed page" as the copyright notice for easier identification within
177 | third-party archives.
178 | 
179 |    Copyright [yyyy] [name of copyright owner]
180 | 
181 |    Licensed under the Apache License, Version 2.0 (the "License");
182 |    you may not use this file except in compliance with the License.
183 |    You may obtain a copy of the License at
184 | 
185 |      http://www.apache.org/licenses/LICENSE-2.0
186 | 
187 |    Unless required by applicable law or agreed to in writing, software
188 |    distributed under the License is distributed on an "AS IS" BASIS,
189 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
190 |    See the License for the specific language governing permissions and
191 |    limitations under the License.
192 | 


--------------------------------------------------------------------------------