1 /*
2 * Entreri, an entity-component framework in Java
3 *
4 * Copyright (c) 2013, Michael Ludwig
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without modification,
8 * are permitted provided that the following conditions are met:
9 *
10 * Redistributions of source code must retain the above copyright notice,
11 * this list of conditions and the following disclaimer.
12 * Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
20 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
23 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27 package com.lhkbob.entreri.task;
28
29 /**
30 * Result represents a computed result, preferably that of a bulk computation, performed
31 * by a Task. Results allow Taskss to easily pass data to other tasks in the same job that
32 * might be interested in their computations.
33 * <p/>
34 * Tasks that wish to expose results define classes that extend Result and provide the
35 * actual result data. During processing of a task, result instances are created and
36 * supplied to all future tasks by calling {@link Job#report(Result)}.
37 * <p/>
38 * To receive computed results, Tasks define <code>public void report(T extends
39 * Result)</code> methods that are invoked through reflection by the job when a compatible
40 * result is reported.
41 *
42 * @author Michael Ludwig
43 */
44 public class Result {
45 /**
46 * <p/>
47 * Return true if this result is a "singleton" result. A singleton result is a type of
48 * result that is can only be reported once per execution of a job. The job verifies
49 * that singleton results are supplied at most once per job execution. Most results
50 * should return false. The returned value should be the same for every instance of a
51 * type, it should not depend on the state of the instance.
52 * <p/>
53 * Singleton results should only be used when the computation of the result produces
54 * all of the result data. As an example, a 3D engine might assign entities to lights,
55 * and each unique configuration of lights on an entity is a "light group". It makes
56 * more sense to provide a single result that describes all light groups than
57 * individual results for each group. They are packed into a single result because
58 * each group is dependent on the others to guarantee its uniqueness.
59 * <p/>
60 * As a counter example, computing potentially visible sets for a 3D engine should not
61 * be a singleton result. A result that contains the view and set of visible entities
62 * is a self-contained result, other views or cameras do not affect the PVS results.
63 * <p/>
64 * The default implementation returns false. Subtypes are free to override it, but it
65 * must return the same value for all instances of a given type.
66 *
67 * @return True if this result should only be supplied at most once during each frame
68 */
69 public boolean isSingleton() {
70 return false;
71 }
72 }