Quick-start with JPAstreamer

This section helps you get started with JPAstreamer in a few minutes. The process can be summed up in four steps:

Installing JPAstreamer
Build your project to generate fields
Initiate JPAstreamer
Streaming a table

The provided guide does not intend to be an exhaustive explanation of these steps but rather provide enough information to set you off streaming in no time. Hence, most of the topics are explained in greater depth throughout the JPAstreamer documentation.

Use of JPAstreamer requires Java 8 or later.

This guide assumes you are starting from an existing project that conveys to the standard JPA specification i.e. represent database tables as Entities etc.

Installing JPAstreamer

The installation is performed by notifying your build tool that the JPAstreamer dependency is required to compile your source code. This is accomplished by using either of the following dependencies for Maven or Gradle.

Maven

Install JPAStreamer by adding the following code in the project’s pom.xml-file:

<dependencies>
    <dependency> (1)
        <groupId>com.speedment.jpastreamer</groupId>
        <artifactId>jpastreamer-core</artifactId>
        <version>${jpa-streamer-version}</version>
    </dependency>
</dependencies>

<plugins>
    <plugin> (2)
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
            <execution>
                <phase>generate-sources</phase>
                <goals>
                    <goal>add-source</goal>
                </goals>
                <configuration>
                    <sources>
                        <source>${project.build.directory}/generated-sources/annotations</source>(3)
                    </sources>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>

1	The JPAstreamer core dependency
2	Picks up the generated metamodel as an additional source directory
3	Path to the generated sources

Gradle

Install JPAStreamer by adding the following code in the project’s build.gradle-file:

repositories {
	mavenCentral()
}

dependencies { (1)
    compile "com.speedment.jpastreamer:jpastreamer-core:version"
    annotationProcessor "com.speedment.jpastreamer:fieldgenerator-standard:version"
}

sourceSets { (2)
    main {
        java {
            srcDir 'src/main/java'
            srcDir 'target/generated-sources/annotations'(3)
        }
    }
}

1	The required JPAstreamer dependencies
2	Picks up the generated metamodel as an additional source directory
3	Path to the generated sources

Build your project to generate fields

JPAstreamer relies on an annotation processor to generate the static metamodel classes required for the type-safe Stream parameters. This generation automatically takes place during compile time. Once you have added the JPAstreamer dependency, just go ahead and build your project. The metamodel is generated into the target folder in the same package as the corresponding Entity.

You may have to manually configure the output target folder as a source folder, or else the runtime compiler may not be aware of the generated classes. See Install with Maven or Install with Gradle for instructions on how to perform this configuration with Maven and Gradle respectively.

Initiate JPAstreamer

JPAstreamer does not need to be manually configured to recognize the underlying data source. Instead, it is using the existing description of the persistence unit. For example:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.2"
             xmlns="http://xmlns.jcp.org/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
     http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd">

    <persistence-unit name="sakila" transaction-type="RESOURCE_LOCAL">
        <description>MySQL Sakila Example Database</description>
        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
        <properties>
            <!-- Configuring The Database Connection Details -->
            <property name="javax.persistence.jdbc.driver" value="com.mysql.cj.jdbc.Driver" />
            <property name="javax.persistence.jdbc.url" value="jdbc:mysql://localhost:3306/sakila" />

            <!-- ... -->

        </properties>
    </persistence-unit>
</persistence>

After installation, JPAstreamer is initialized with the name of the persistance unit:

JPAStreamer jpaStreamer = JPAStreamer.of("sakila"); (1)

1	"sakila" is to be replaced with the name of your persistence unit

Streaming a table

The persistence unit described in the example above is the MySQL Sakila example database. This models a traditional movie rental shop and contains tables such as Film. In this example, the entity-bean corresponding to the film-table looks like this:

@Entity
@Table(name = "film", schema = "sakila")
public class Film {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "film_id", columnDefinition = "smallint(5)")
    private Integer filmId;

    @Column(name = "title", columnDefinition = "varchar(255)")
    private String title;

    // ... additional fields and corresponding getters and setters
}

To stream the entries of this table, simply call jpaStreamer.stream() and provide the entity class:

jpaStreamer.stream(Film.class) (1)
    .forEach(System.out::println);

1	`Film.class` refers to the annotated `Entity` that models the table which is to be streamed

This will yield the following output:

Film {filmId=1, title='ACADEMY DINOSAUR', ...
Film {filmId=2, title='ACE GOLDFINGER', ...
Film {filmId=3, title='ADAPTATION HOLES', ...
Film {filmId=4, title='AFFAIR PREJUDICE', ...
Film {filmId=5, title='AFRICAN EGG', ...

To release any resources potentially held by JPAstreamer, simply close the streamer using the command jpaStreamer.close();

jpaStreamer.close();

Code Generator Settings

You can configure where the annotation processor generates entities and how they are named using the Maven Compiler Plugin. This section describes how that is done.

Package name

By default, all generated classes will be placed under target/generated-sources/annotations in a package that matches that of the original entity. Thus, a com.foo.Film.class entity will yield a target/generated-sources/annotations/com/foo/Film$.class.

You can change the package name for all entities by setting the compiler argument jpaStreamerPackage.

If your entities have package private fields, they may not be accessible to the generated Entities. Therefore, take caution when deciding to place the generated entities in a separate package.

Generated entity name

As shown in examples throughout the user guide, generated entities are by default given the name of the original entity with an extra $ at the end. Meaning an entity Foo.class will yield a Foo$.class. You can change the naming convention by setting the compiler argument jpaStreamerPrefix and jpaStreamerSuffix. The prefix will be added at the start of the original entity name and the suffix will be appended at the end.

The default suffix $ applies if no custom values are provided via the compiler arguments. If just one of jpaStreamerPrefix and jpaStreamerSuffix is set, the other will automatically default to an empty string. For example, just setting the prefix to A will result in entities with the name AFoo.class. Take note that the naming pattern must adhere to Java’s naming conventions.

Here is a complete example configuration of the plugin that sets both the package name, prefix, and suffix.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.10.1</version>
    <configuration>
        <compilerArgs>
            <arg>-AjpaStreamerPackage=com.speedment.jpastreamer.test</arg> (1)
            <arg>-AjpaStreamerPrefix=A</arg> (2)
            <arg>-AjpaStreamerSuffix=B</arg> (3)
        </compilerArgs>
    </configuration>
</plugin>

1	Package name is set to `com.speedment.jpastreamer.test`
2	Entity prefix is set to A (start)
3	Entity suffix is set to B (ending)

In the above example, all generated entities will be placed in /target/generated-sources/annotations/com.speedment.jpastreamer.test. An original entity with the name Film will yeild a generated entity called AFilmB.

Next Steps

Now that you have access to JPAstreamer it’s time to put the expressiveness of Java Streams to work. If you are not yet familiar with the Stream API, you may find our guide on Stream Fundamentals helpful.

Otherwise, feel free to check out the collection of examples of JPAStreamer usage.