com.hazelcast.jet

## Interface Traverser<T>

- Type Parameters:
    `T` - traversed item type
  All Known Implementing Classes:
    AppendableTraverser, ResettableSingletonTraverser
  Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public interface Traverser<T>

  Traverses a potentially infinite sequence of non-`null` items. Each invocation of `next()` consumes and returns the next item in the sequence if available, or `null` if not. If the traverser is null-terminated, getting a `null` means it's exhausted and will keep returning `null` forever.

  All transformation methods (`map()`, `append()`, `peek()`, ...) are allowed to either return a new instance or to modify `this` instance. For correct functionality, you must always use the returned value and stop using the original instance.

  Since:
    3.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default Traverser<T>` | `append(T item)` Returns a traverser that will return all the items of this traverser, plus an additional item once this one returns `null`.
    `default Traverser<T>` | `dropWhile(Predicate<? super T> predicate)` Returns a traverser that will emit a suffix of the original traverser, starting from the item for which the predicate fails (inclusive).
    `default Traverser<T>` | `filter(Predicate<? super T> filterFn)` Returns a traverser that will emit the same items as this traverser, but only those that pass the given predicate.
    `default <R> Traverser<R>` | `flatMap(Function<? super T,? extends Traverser<? extends R>> flatMapFn)` Returns a traverser that will apply the given mapping function to each item retrieved from this traverser and emit all the items from the resulting traversers, which must be null-terminated.
    `default <R> Traverser<R>` | `map(Function<? super T,? extends R> mapFn)` Returns a traverser that will emit the results of applying `mapFn` to this traverser's items.
    `T` | `next()` Returns the next item, removing it from this traverser.
    `default Traverser<T>` | `onFirstNull(Runnable action)` Returns a traverser that will emit the same items as this traverser and additionally run the supplied action the first time this traverser returns `null`.
    `default Traverser<T>` | `peek(Consumer<? super T> action)` Returns a traverser that will emit the same items as this traverser, additionally passing each (non-null) item to the supplied consumer.
    `default Traverser<T>` | `prepend(T item)` Returns a traverser which prepends an additional item in front of all the items of this traverser.
    `default Traverser<T>` | `takeWhile(Predicate<? super T> predicate)` Returns a traverser that will emit a prefix of the original traverser, up to the item for which the predicate fails (exclusive).

- - ### Method Detail

    - #### next

          T next()

      Returns the next item, removing it from this traverser. If no item is available, returns `null`. If this traverser is null-terminated, getting a `null` means it's exhausted and will keep returning `null` forever. Otherwise, trying again later may produce one.

    - #### map

          @Nonnull
           @CheckReturnValue
          default <R> Traverser<R> map(@Nonnull
                                                                   Function<? super T,? extends R> mapFn)

      Returns a traverser that will emit the results of applying `mapFn` to this traverser's items. If `mapFn` returns `null` for an item, the returned traverser drops it and immediately moves on to the next item from this traverser. This way `mapFn` can perform filtering in addition to transformation.

    - #### filter

          @Nonnull
           @CheckReturnValue
          default Traverser<T> filter(@Nonnull
                                                                  Predicate<? super T> filterFn)

      Returns a traverser that will emit the same items as this traverser, but only those that pass the given predicate.

    - #### flatMap

          @Nonnull
           @CheckReturnValue
          default <R> Traverser<R> flatMap(@Nonnull
                                                                       Function<? super T,? extends Traverser<? extends R>> flatMapFn)

      Returns a traverser that will apply the given mapping function to each item retrieved from this traverser and emit all the items from the resulting traversers, which must be null-terminated.

      The function must not return null traverser, but can return an empty traverser.

    - #### takeWhile

          @Nonnull
           @CheckReturnValue
          default Traverser<T> takeWhile(@Nonnull
                                                                     Predicate<? super T> predicate)

      Returns a traverser that will emit a prefix of the original traverser, up to the item for which the predicate fails (exclusive).

    - #### dropWhile

          @Nonnull
           @CheckReturnValue
          default Traverser<T> dropWhile(@Nonnull
                                                                     Predicate<? super T> predicate)

      Returns a traverser that will emit a suffix of the original traverser, starting from the item for which the predicate fails (inclusive).

    - #### append

          @Nonnull
           @CheckReturnValue
          default Traverser<T> append(@Nonnull
                                                                  T item)

      Returns a traverser that will return all the items of this traverser, plus an additional item once this one returns `null`. After that it continues forwarding the return values of this traverser. It is meant to be used on finite traversers.

      Default implementations always returns a new traverser instance. If you need to append multiple objects or use this method frequently, `AppendableTraverser` might be a better choice.

    - #### prepend

          @Nonnull
           @CheckReturnValue
          default Traverser<T> prepend(@Nonnull
                                                                   T item)

      Returns a traverser which prepends an additional item in front of all the items of this traverser.

    - #### peek

          @Nonnull
           @CheckReturnValue
          default Traverser<T> peek(@Nonnull
                                                                Consumer<? super T> action)

      Returns a traverser that will emit the same items as this traverser, additionally passing each (non-null) item to the supplied consumer.

    - #### onFirstNull

          @Nonnull
           @CheckReturnValue
          default Traverser<T> onFirstNull(@Nonnull
                                                                       Runnable action)

      Returns a traverser that will emit the same items as this traverser and additionally run the supplied action the first time this traverser returns `null`.

Copyright © 2019. All rights reserved.