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:

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();

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.

jpaStreamer.close();