Remove API warning and improve JavaDoc. Fix #105

application/src/main/java/com/speedment/jpastreamer/application/JPAStreamer.java

@@ -185,7 +185,7 @@ default <T> Stream<T> stream(final Class<T> entityClass) {
      */
     default <T> Stream<T> stream(final Projection<T> projection) {
         requireNonNull(projection);
-        return stream(StreamConfiguration.of(projection.entityClass()).select(projection));
+        return stream(StreamConfiguration.of(projection.entityClass()).selecting(projection));
     }
 
     /**

provider/builder-standard/src/test/java/com/speedment/jpastreamer/builder/standard/internal/BaseStreamBuilderTest.java

@@ -221,17 +221,12 @@ public StreamConfiguration<T> joining(Field<T> field, JoinType joinType) {
         }
 
         @Override
-        public StreamConfiguration<T> select(Field<T> first, Field<T>... other) {
-            throw new UnsupportedOperationException();
-        }
-
-        @Override
-        public Optional<Projection<T>> select() {
+        public Optional<Projection<T>> selections() {
             return Optional.ofNullable(projection);
         }
 
         @Override
-        public StreamConfiguration<T> select(Projection<T> projection) {
+        public StreamConfiguration<T> selecting(Projection<T> projection) {
             throw new UnsupportedOperationException();
         }
     }

provider/renderer-standard/src/main/java/com/speedment/jpastreamer/renderer/standard/internal/StandardRenderer.java

@@ -67,8 +67,8 @@ public <E, T, S extends BaseStream<T, S>> RenderResult<E, T, S> render(final Pip
         final Criteria<E, E> criteria = criteriaFactory.createCriteria(entityManager, entityClass);
         criteria.getRoot().alias(pipeline.root().getSimpleName());
 
-        if (streamConfiguration.select().isPresent()) {
-            final Projection<E> projection = streamConfiguration.select().get();
+        if (streamConfiguration.selections().isPresent()) {
+            final Projection<E> projection = streamConfiguration.selections().get();
             final Path<?>[] columns = projection.fields().stream().map(field -> criteria.getRoot().get(field.columnName())).toArray(Path[]::new);
             final CompoundSelection<E> selection = criteria.getBuilder().construct(projection.entityClass(), columns);
 

provider/streamconfiguration-standard/src/main/java/com/speedment/jpastreamer/streamconfiguration/standard/internal/StandardStreamConfiguration.java

@@ -57,25 +57,18 @@ public Set<JoinConfiguration<T>> joins() {
     public StreamConfiguration<T> joining(final Field<T> field, final JoinType joinType) {
         requireNonNull(field);
         requireNonNull(joinType);
-        final Set<JoinConfiguration<T>> newjoins = new HashSet<>(joinConfigurations);
-        newjoins.add(new StandardJoinConfiguration<>(field, joinType));
-        return new StandardStreamConfiguration<>(entityClass, projection, newjoins);
+        final Set<JoinConfiguration<T>> newJoins = new HashSet<>(joinConfigurations);
+        newJoins.add(new StandardJoinConfiguration<>(field, joinType));
+        return new StandardStreamConfiguration<>(entityClass, projection, newJoins);
     }
 
     @Override
-    public Optional<Projection<T>> select() {
+    public Optional<Projection<T>> selections() {
         return Optional.ofNullable(projection);
     }
 
-    @SuppressWarnings("varargs")
-    @SafeVarargs
     @Override
-    public final StreamConfiguration<T> select(Field<T> first, Field<T>... other) {
-        return select(Projection.select(first, other));
-    }
-
-    @Override
-    public StreamConfiguration<T> select(Projection<T> projection) {
+    public StreamConfiguration<T> selecting(Projection<T> projection) {
         requireNonNull(projection);
         return new StandardStreamConfiguration<>(entityClass, projection, joinConfigurations);
     }

streamconfiguration/src/main/java/com/speedment/jpastreamer/streamconfiguration/StreamConfiguration.java

@@ -37,7 +37,7 @@ public interface StreamConfiguration<T> {
      * a future Stream.
      *
      * @return the entity class that is to appear in
-     *         a future Stream
+     * a future Stream
      */
     Class<T> entityClass();
 
@@ -50,7 +50,7 @@ public interface StreamConfiguration<T> {
      * by stream consumers.
      *
      * @return the fields that shall be joined in
-     *         a future stream
+     * a future stream
      */
     Set<JoinConfiguration<T>> joins();
 
@@ -63,11 +63,12 @@ public interface StreamConfiguration<T> {
      * This prevents the N+1 problem if the field is accessed in
      * elements in the future Stream.
      * </p>
+     *
      * @param field to join
      * @return a new StreamConfiguration configured with
-     *         the provided {@code field} so that it will be
-     *         eagerly joined when producing elements in the future Stream
-     *         using {@link JoinType#LEFT}
+     * the provided {@code field} so that it will be
+     * eagerly joined when producing elements in the future Stream
+     * using {@link JoinType#LEFT}
      */
     default StreamConfiguration<T> joining(final Field<T> field) {
         return joining(field, JoinType.LEFT);
@@ -82,19 +83,52 @@ default StreamConfiguration<T> joining(final Field<T> field) {
      * This prevents the N+1 problem if the field is accessed in
      * elements in the future Stream.
      * </p>
+     *
      * @param field to join
      * @return a new StreamConfiguration configured with
-     *         the provided {@code field} so that it will be
-     *         eagerly joined when producing elements in the future Stream
-     *         using the provided {@code joinType}
+     * the provided {@code field} so that it will be
+     * eagerly joined when producing elements in the future Stream
+     * using the provided {@code joinType}
      */
     StreamConfiguration<T> joining(final Field<T> field, final JoinType joinType);
 
-    Optional<Projection<T>> select();
-
-    StreamConfiguration<T> select(final Field<T> first, final Field<T>... other);
+    /**
+     * Returns the projected columns to use when creating entities or
+     * {@link Optional#empty()} if no projection should be used.
+     * <p>
+     * A corresponding entity constructor must exist.
+     *
+     * @return the projected columns to use when creating entities or
+     * {@link Optional#empty()} if no projection should be used
+     */
+    Optional<Projection<T>> selections();
 
-    StreamConfiguration<T> select(final Projection<T> projection);
+    /**
+     * Selects the projected columns to initialize when creating
+     * <em>initial</em> entities in a future stream.
+     * <p>
+     * If this method is never called, all columns will be selected.
+     * <p>
+     * Un-selected columns will be set to their default values (e.g. null or 0)
+     * <p>
+     * A corresponding entity constructor must exist. For example,
+     * if a Person with columns {@code int id} and {@code String name}
+     * (and potentially many other columns) and the columns {@code id}
+     * and {@code name} are used for projection, then the entity
+     * Person must have a constructor:
+     * <pre>{@code
+     *     public Person(int id, String name) {
+     *         setId(id);
+     *         setName(name);
+     *     }
+     * }</pre>
+     *
+     * @return a new StreamConfiguration configured with
+     * the provided {@code projection} so that it will use
+     * the projected columns to initialize when creating
+     * <em>initial</em> entities in a future stream
+     */
+    StreamConfiguration<T> selecting(final Projection<T> projection);
 
     /**
      * Creates and returns a new StreamConfiguration that can be used
@@ -105,7 +139,7 @@ default StreamConfiguration<T> joining(final Field<T> field) {
      * any object obtained from instances (or subsequent derived instances)
      * are immutable or unmodifiable.
      *
-     * @param <T> The element type (type of a class token)
+     * @param <T>         The element type (type of a class token)
      * @param entityClass a class token for an entity class (annotated with {@code @Entity})
      * @return a new JPAStreamerBuilder
      */
@@ -117,8 +151,22 @@ static <T> StreamConfiguration<T> of(final Class<T> entityClass) {
     }
 
     interface JoinConfiguration<T> {
+        /**
+         * Returns the {@link Field} for this JoinConfiguration.
+         * <p>
+         * The field will be eagerly joined into the initial stream
+         * of entities.
+         *
+         * @return the {@link Field} for this JoinConfiguration
+         */
         Field<T> field();
+
+        /**
+         * Returns the {@link JoinType} for this JoinConfiguration.
+         *
+         * @return the {@link JoinType} for this JoinConfiguration
+         */
         JoinType joinType();
     }
 
-}
+}