<commit_before>h1. Avro RPC Quick Start

*Author: "<NAME>":http://people.apache.org/~phunt/* "(twitter)":http://twitter.com/phunt

"Avro is a data serialization system."
"http://hadoop.apache.org/avro/":http://hadoop.apache.org/avro/

This quick start "document/project":http://github.com/phunt/avro-rpc-quickstart is current hosted at github.

h2. Summary

This is a template/blueprint project intended as a Quick Start introduction to Avro. You'll learn how to declare a protocol, generate and compile your code, and run a working "Hello World" type example. This project supports building with either Maven or Ant/Ivy, choose one.

h2. Requirements

If you decide to use Maven you will need the Avro Maven Plugin to compile the protocol specification. I've included the Avro Maven plugin jar file in this repository for simplicity and to get you started quickly. However you can examine the source here: "avro-maven-plugin":http://github.com/phunt/avro-maven-plugin

Ant based build has no additional requirements (just ant).

h2. Introduction

The sample application included in this project simulates a remote service, Mail, where Avro RPC is used to send a message using the service. This document details how to build and run the sample using either Ant or Maven. In either case the Avro jar files (and jars they depend upon) will be downloaded automatically.

In this sample project you will find four sets of files:
# This documentation
# Ant/Ivy build files
# Maven build file
# Sample application - i.e. avro protocol declaration and java Main program

h2. Overview of the files

h3. Ant/Ivy build files

* build.xml - the Ant build file
* ivy.xml - this file specifies the dependencies of the project, primarily the Avro jar file

h3. Maven build file

* pom.xml - this file specifies the dependencies of the project, primarily the Avro jar file

The profile section adds the ibiblio repository, which holds the Avro dependencies.

<notextile><pre><code>    &lt;profile>
      &lt;id>default&lt;/id>
      &lt;repositories>
        &lt;repository>
          &lt;id>ibiblio&lt;/id>
          &lt;name>www.ibiblio.org&lt;/name>
          &lt;url>http://people.apache.org/repo/m2-ibiblio-rsync-repository&lt;/url>
        &lt;/repository> 
      &lt;/repositories> 
    &lt;/profile>
</code></pre></notextile>

You'll also see the plugin section, which contains:

This plugin element causes the Avro Maven Plugin's protocol goal defined in "avro-maven-plugin":http://github.com/phunt/avro-maven-plugin to run during the "generate-sources" maven phase.

<notextile><pre><code>      &lt;plugin>
        &lt;groupId>org.apache.avro&lt;/groupId>
        &lt;artifactId>avro-maven-plugin&lt;/artifactId>
        &lt;version>1.0-SNAPSHOT&lt;/version>
        &lt;executions>
          &lt;execution>
            &lt;phase>generate-sources&lt;/phase>
            &lt;goals>
              &lt;goal>protocol&lt;/goal>
            &lt;/goals>
          &lt;/execution>
        &lt;/executions>
      &lt;/plugin>
</code></pre></notextile>

The Paranamer plugin is necessary for Avro to access method parameter metadata (i.e. names) during runtime.

<notextile><pre><code>      &lt;plugin>
        &lt;groupId>com.thoughtworks.paranamer&lt;/groupId>
        &lt;artifactId>paranamer-maven-plugin&lt;/artifactId>
        &lt;executions>
          &lt;execution>
            &lt;id>run&lt;/id>  &lt;!-- id is optional -->
            &lt;configuration>
              &lt;sourceDirectory>${project.build.directory}/generated-sources/avro&lt;/sourceDirectory>
              &lt;outputDirectory>${project.build.directory}/classes&lt;/outputDirectory>
            &lt;/configuration>        
            &lt;goals>
              &lt;goal>generate&lt;/goal>
            &lt;/goals>
          &lt;/execution>
        &lt;/executions>
      &lt;/plugin>
</code></pre></notextile>

This tells Maven to target 1.5 JVM:

<notextile><pre><code>      &lt;plugin>
        &lt;artifactId>maven-compiler-plugin&lt;/artifactId>
        &lt;configuration>
          &lt;source>1.5&lt;/source>
          &lt;target>1.5&lt;/target>
        &lt;/configuration>
      &lt;/plugin>
</code></pre></notextile>

h3. mail.avpr - Avro Protocol Declaration

src/main/avro should contain all of the Avro protocol & schema specifications. mail.avpr declares our simple "Mail" service. You will see:
# the name & namespace of the protocol
# any specialized types used in the messages, Message in this case
# we are declaring a "send" message type which takes a Message as an argument and returns a result string

Read more about Avro's "protocol declaration":http://hadoop.apache.org/avro/docs/current/spec.html#Protocol+Declaration

h3. Main.java - the main() routine of the Mail sample

src/main/java/example/Main.java 
# the MailImpl class implements the Mail protocol defined in mail.avpr
# the startServer() method starts the server which implements the Mail service (Mail/MailImpl)
# the main function takes three arguments; to, from and body of the message. After the server is started a Mail client is created, attached to the service, and used to send a "Message", the result of the RPC call is printed to the console.

h2. Compiling the sample

With either build system, maven or ant, all generated files (source, class, etc...) are written to the "target" directory.

Maven:
<code>
mvn compile
</code>

Ant/Ivy:
<code>
ant compile
</code>

*Note*: integration with eclipse is very simple. If you are using Ant, create a project and add the Main.java and jars contained in the lib directory (created/downloaded by ivy as part of compiling the project using build.xml). If using Maven just type "mvn eclipse:eclipse" (see the "maven-eclipse-plugin":http://maven.apache.org/plugins/maven-eclipse-plugin/ documentation for more details).

h2. Running the sample

Maven:
<code>
mvn -e exec:java -Dexec.mainClass=example.Main -Dexec.args='avro_user pat Hello_World'
</code>

Ant/Ivy:
<code>
ant exec:java
</code>
<commit_msg>jars are in target/lib, not toplevel lib<commit_after>h1. Avro RPC Quick Start

*Author: "<NAME>":http://people.apache.org/~phunt/* "(twitter)":http://twitter.com/phunt

"Avro is a data serialization system."
"http://hadoop.apache.org/avro/":http://hadoop.apache.org/avro/

This quick start "document/project":http://github.com/phunt/avro-rpc-quickstart is current hosted at github.

h2. Summary

This is a template/blueprint project intended as a Quick Start introduction to Avro. You'll learn how to declare a protocol, generate and compile your code, and run a working "Hello World" type example. This project supports building with either Maven or Ant/Ivy, choose one.

h2. Requirements

If you decide to use Maven you will need the Avro Maven Plugin to compile the protocol specification. I've included the Avro Maven plugin jar file in this repository for simplicity and to get you started quickly. However you can examine the source here: "avro-maven-plugin":http://github.com/phunt/avro-maven-plugin

Ant based build has no additional requirements (just ant).

h2. Introduction

The sample application included in this project simulates a remote service, Mail, where Avro RPC is used to send a message using the service. This document details how to build and run the sample using either Ant or Maven. In either case the Avro jar files (and jars they depend upon) will be downloaded automatically.

In this sample project you will find four sets of files:
# This documentation
# Ant/Ivy build files
# Maven build file
# Sample application - i.e. avro protocol declaration and java Main program

h2. Overview of the files

h3. Ant/Ivy build files

* build.xml - the Ant build file
* ivy.xml - this file specifies the dependencies of the project, primarily the Avro jar file

h3. Maven build file

* pom.xml - this file specifies the dependencies of the project, primarily the Avro jar file

The profile section adds the ibiblio repository, which holds the Avro dependencies.

<notextile><pre><code>    &lt;profile>
      &lt;id>default&lt;/id>
      &lt;repositories>
        &lt;repository>
          &lt;id>ibiblio&lt;/id>
          &lt;name>www.ibiblio.org&lt;/name>
          &lt;url>http://people.apache.org/repo/m2-ibiblio-rsync-repository&lt;/url>
        &lt;/repository> 
      &lt;/repositories> 
    &lt;/profile>
</code></pre></notextile>

You'll also see the plugin section, which contains:

This plugin element causes the Avro Maven Plugin's protocol goal defined in "avro-maven-plugin":http://github.com/phunt/avro-maven-plugin to run during the "generate-sources" maven phase.

<notextile><pre><code>      &lt;plugin>
        &lt;groupId>org.apache.avro&lt;/groupId>
        &lt;artifactId>avro-maven-plugin&lt;/artifactId>
        &lt;version>1.0-SNAPSHOT&lt;/version>
        &lt;executions>
          &lt;execution>
            &lt;phase>generate-sources&lt;/phase>
            &lt;goals>
              &lt;goal>protocol&lt;/goal>
            &lt;/goals>
          &lt;/execution>
        &lt;/executions>
      &lt;/plugin>
</code></pre></notextile>

The Paranamer plugin is necessary for Avro to access method parameter metadata (i.e. names) during runtime.

<notextile><pre><code>      &lt;plugin>
        &lt;groupId>com.thoughtworks.paranamer&lt;/groupId>
        &lt;artifactId>paranamer-maven-plugin&lt;/artifactId>
        &lt;executions>
          &lt;execution>
            &lt;id>run&lt;/id>  &lt;!-- id is optional -->
            &lt;configuration>
              &lt;sourceDirectory>${project.build.directory}/generated-sources/avro&lt;/sourceDirectory>
              &lt;outputDirectory>${project.build.directory}/classes&lt;/outputDirectory>
            &lt;/configuration>        
            &lt;goals>
              &lt;goal>generate&lt;/goal>
            &lt;/goals>
          &lt;/execution>
        &lt;/executions>
      &lt;/plugin>
</code></pre></notextile>

This tells Maven to target 1.5 JVM:

<notextile><pre><code>      &lt;plugin>
        &lt;artifactId>maven-compiler-plugin&lt;/artifactId>
        &lt;configuration>
          &lt;source>1.5&lt;/source>
          &lt;target>1.5&lt;/target>
        &lt;/configuration>
      &lt;/plugin>
</code></pre></notextile>

h3. mail.avpr - Avro Protocol Declaration

src/main/avro should contain all of the Avro protocol & schema specifications. mail.avpr declares our simple "Mail" service. You will see:
# the name & namespace of the protocol
# any specialized types used in the messages, Message in this case
# we are declaring a "send" message type which takes a Message as an argument and returns a result string

Read more about Avro's "protocol declaration":http://hadoop.apache.org/avro/docs/current/spec.html#Protocol+Declaration

h3. Main.java - the main() routine of the Mail sample

src/main/java/example/Main.java 
# the MailImpl class implements the Mail protocol defined in mail.avpr
# the startServer() method starts the server which implements the Mail service (Mail/MailImpl)
# the main function takes three arguments; to, from and body of the message. After the server is started a Mail client is created, attached to the service, and used to send a "Message", the result of the RPC call is printed to the console.

h2. Compiling the sample

With either build system, maven or ant, all generated files (source, class, etc...) are written to the "target" directory.

Maven:
<code>
mvn compile
</code>

Ant/Ivy:
<code>
ant compile
</code>

*Note*: integration with eclipse is very simple. If you are using Ant, create a project and add the Main.java and jars contained in the target/lib directory (created/downloaded by ivy as part of compiling the project using build.xml). If using Maven just type "mvn eclipse:eclipse" (see the "maven-eclipse-plugin":http://maven.apache.org/plugins/maven-eclipse-plugin/ documentation for more details).

h2. Running the sample

Maven:
<code>
mvn -e exec:java -Dexec.mainClass=example.Main -Dexec.args='avro_user pat Hello_World'
</code>

Ant/Ivy:
<code>
ant exec:java
</code>

{'fraction_non_alphanumeric': 0.10637059214903526, 'fraction_numerical': 0.00332667997338656, 'mean_word_length': 3.4719226478244702, 'pattern_counts': {'":': 16, '<': 69, '<?xml version=': 0, '>': 199, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5153388', 'n_tokens_mistral': 3623, 'n_tokens_neox': 3496, 'n_words': 1254}