net.sf.staccatocommons.collections.stream.Stream Maven / Gradle / Ivy

Go to download
/**
 *  Copyright (c) 2011, The Staccato-Commons Team
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation; version 3 of the License.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 */

package net.sf.staccatocommons.collections.stream;

import java.io.Serializable;

import net.sf.staccatocommons.collections.restrictions.Projection;
import net.sf.staccatocommons.collections.restrictions.Repeatable;
import net.sf.staccatocommons.defs.Executable;
import net.sf.staccatocommons.defs.partial.ContainsAware;
import net.sf.staccatocommons.defs.partial.SizeAware;
import net.sf.staccatocommons.iterators.thriter.Thriterator;
import net.sf.staccatocommons.restrictions.check.NonNull;

/**
 * A {@link Stream} is a lazy, rich-interfaced, {@link Iterable}, chained
 * functional-style object that can retrieve and process an arbitrary - and
 * potentially unbound - amount of other objects of a parameterized type. Such
 * objects are called elements, and are generated by another object, called
 * source. Some examples of elements and its source are:
 * 
 * Elements in a collection
 * Files in a directory
 * Characters in a string
 * Lines in a file
 * Rows in a result set
 * Virtually anything that has sense to iterate through
 * 
 * 
 * Streams have the following properties:
 * 
 * Operation oriented: A stream represents a single and eventually complex
 * transformation over a source of objects; it is not a
 * container
 * Reference Semantics: A stream internal state is meaningless, and Streams
 * do not override Object's {@link #equals(Object)}, {@link #hashCode()} nor
 * {@link #toString()}
 * Non persistent: Streams are not {@link Serializable} Thus, they should
 * not be used as attributes of long-living objects.
 * One-Message: Given a stream instance, only one message can be sent to it,
 * sending more than one message to it has an undefined result, as a
 * consequence, it may be iterated only once. There are three exceptions to this
 * rule, though:
 * 
 * Methods inherited from {@link Object} like {@link #toString()} and
 * {@link #hashCode()}. None of those methods affect the transformation nor the
 * underlying source
 * {@link #isEmpty()}: it may be sent multiple times and grants consistent
 * results as long as no other message except of those at previous item is sent.
 * This message does not affect the transformation, but may modify the
 * underlying source
 * Streams returned by class or instance methods annotated with
 * {@link Repeatable}, like {@link #force()} or {@link Streams#cons(Object)}.
 * Such streams may be reused and receive any message any number of times, and
 * grant consistent results, including repeatable iteration order.
 * 
 * 
 * Lazy projections: all of the - many - transformations exposed by streams
 * that are annotated as {@link Projection} are lazy. Such methods do also work
 * with very large o potentially infinte streams.
 * 
 * 
 * Concrete, simple streams, collection handling-oriented, may be instantiated
 * through {@link Streams} class. Other concrete streams are be provided by
 * other staccato-commons libraries.
 * 
 * Aside from these concrete streams, client code may also implement new ones.
 * In order to do that, it must not implement this interface
 * directly, but inherit from {@link AbstractStream}, which implements all
 * methods except of {@link #iterator()}
 * 
 * @author fbulgarelli
 * 
 * @param 
 *          the type of object the stream is source of
 */
public interface Stream extends //
  Indexed, //
  Appendable, //
  Branchable, //
  Collectible, //
  ContainsAware, //
  Crossable, //
  Deconstructable, //
  Filterable, //
  Foldable, //
  Interscalable, //
  Iterable, //
  Mappable, //
  Groupable, //
  Printable, //
  Reversable, //
  Searchable, //
  SizeAware, //
  Sortable, //
  Testeable, //
  Transformable, //
  Zippeable {

  Thriterator iterator();

  /**
   * Executes the given {@link Executable} block for each element.
   * 
   * This message is equivalent to a for-each loop over this {@link Stream}
   * 
   * @param block
   * @since 1.2
   */
  void forEach(@NonNull Executable block);

  /**
   * 
   * @param block
   * @return
   * @since 1.1 original version, replaced by {@link #forEach(Executable)}
   * @since 1.2 current version, incompatible with previous 1.1
   * 
   */
  Stream each(@NonNull Executable block);

}