1 package com.atlassian.plugin.util.collect;
2
3 /**
4 * A Function that resolves input (of type I) to output (of type O).
5 * <p>
6 * Semantically, this could be a Factory, Generator, Builder, Closure,
7 * Transformer, Resolver or something else entirely. No particular guarantees
8 * are implied by this interface apart from idempotence (see below).
9 * Specifically, implementations may or may not return or accept null and can
10 * optionally block until elements are available or throw
11 * {@link RuntimeException runtime exceptions} if the input is not acceptable
12 * for some reason. Any clients that require a firmer contract should subclass
13 * this interface and document their requirements.
14 * <p>
15 * It is expected that for any two calls to {@link #get(Object)} D the returned
16 * resource will be semantically the same, ie. that the call is effectively
17 * idempotent. Any implementation that violates this should document the fact.
18 * It is not necessary that the resolved object is the same instance or even
19 * implements {@link #equals(Object)} and {@link #hashCode()} however.
20 * <p>
21 * As this interface requires idempotence implementations should be reentrant
22 * and thread-safe.
23 *
24 * @param <I> the descriptor type.
25 * @param <O> the resource type it resolves to.
26 */
27 public interface Function<I, O>
28 {
29 /**
30 * Resolves an output <R> where an input <D> is given.
31 *
32 * @param input an object of type D.
33 * @return the output of type R.
34 */
35 O get(I input);
36 }