001package arez.spy;
002
003import arez.Arez;
004import arez.Component;
005import arez.ComputableValue;
006import arez.ObservableValue;
007import arez.Observer;
008import arez.Task;
009import java.util.Collection;
010import javax.annotation.Nonnull;
011import javax.annotation.Nullable;
012
013/**
014 * Interface for interacting with spy system.
015 */
016public interface Spy
017{
018  /**
019   * Add a spy handler to the list of handlers.
020   * The handler should not already be in the list.
021   *
022   * @param handler the spy handler.
023   */
024  void addSpyEventHandler( @Nonnull SpyEventHandler handler );
025
026  /**
027   * Remove spy handler from list of existing handlers.
028   * The handler should already be in the list.
029   *
030   * @param handler the spy handler.
031   */
032  void removeSpyEventHandler( @Nonnull SpyEventHandler handler );
033
034  /**
035   * Return true if spy events will be propagated.
036   * This means spies are enabled and there is at least one spy event handler present.
037   *
038   * @return true if spy events will be propagated, false otherwise.
039   */
040  boolean willPropagateSpyEvents();
041
042  /**
043   * Report an event in the Arez system.
044   *
045   * @param event the event that occurred.
046   */
047  void reportSpyEvent( @Nonnull Object event );
048
049  /**
050   * Return true if there is a transaction active.
051   *
052   * @return true if there is a transaction active.
053   */
054  boolean isTransactionActive();
055
056  /**
057   * Return the current transaction.
058   * This method should not be invoked unless {@link #isTransactionActive()} returns true.
059   *
060   * @return the current transaction.
061   */
062  @Nonnull
063  TransactionInfo getTransaction();
064
065  /**
066   * Find the component identified by the specified type and id.
067   *
068   * @param type the component type.
069   * @param id   the component id. Should be null if the component is a singleton.
070   * @return the component descriptor matching the specified type and id.
071   */
072  @Nullable
073  ComponentInfo findComponent( @Nonnull String type, @Nonnull Object id );
074
075  /**
076   * Find all the components identified by the specified type.
077   * This collection returned is unmodifiable.
078   *
079   * @param type the component type.
080   * @return the collection of component descriptors of specified type.
081   */
082  @Nonnull
083  Collection<ComponentInfo> findAllComponentsByType( @Nonnull String type );
084
085  /**
086   * Find all the component types in the system.
087   * This is essentially all the types that have at least 1 instance.
088   * This collection returned is unmodifiable.
089   *
090   * @return the collection of component types.
091   */
092  @Nonnull
093  Collection<String> findAllComponentTypes();
094
095  /**
096   * Find all the observables not contained by a native component.
097   * This method should not be invoked unless {@link Arez#areRegistriesEnabled()} returns true.
098   * This collection returned is unmodifiable.
099   *
100   * @return the collection of observables not contained by a native component.
101   */
102  @Nonnull
103  Collection<ObservableValueInfo> findAllTopLevelObservableValues();
104
105  /**
106   * Find all the observers not contained by a native component.
107   * This method should not be invoked unless {@link Arez#areRegistriesEnabled()} returns true.
108   * This collection returned is unmodifiable.
109   *
110   * @return the collection of observers not contained by a native component.
111   */
112  @Nonnull
113  Collection<ObserverInfo> findAllTopLevelObservers();
114
115  /**
116   * Find all the computable values not contained by a native component.
117   * This method should not be invoked unless {@link Arez#areRegistriesEnabled()} returns true.
118   * This collection returned is unmodifiable.
119   *
120   * @return the collection of computable values not contained by a native component.
121   */
122  @Nonnull
123  Collection<ComputableValueInfo> findAllTopLevelComputableValues();
124
125  /**
126   * Find all the "top-level" tasks defined by the system.
127   * This does not return tasks that are used to define Observers etc.
128   * This method should not be invoked unless {@link Arez#areRegistriesEnabled()} returns true.
129   * This collection returned is unmodifiable.
130   *
131   * @return the collection of tasks defined by the context.
132   */
133  @Nonnull
134  Collection<TaskInfo> findAllTopLevelTasks();
135
136  /**
137   * Convert the specified component into an ComponentInfo.
138   *
139   * @param component the Component.
140   * @return the ComponentInfo.
141   */
142  @Nonnull
143  ComponentInfo asComponentInfo( @Nonnull Component component );
144
145  /**
146   * Convert the specified observer into an ObserverInfo.
147   *
148   * @param observer the Observer.
149   * @return the ObserverInfo.
150   */
151  @Nonnull
152  ObserverInfo asObserverInfo( @Nonnull Observer observer );
153
154  /**
155   * Convert the specified observableValue into an ObservableValueInfo.
156   *
157   * @param <T>             The type of the value that is observableValue.
158   * @param observableValue the ObservableValue.
159   * @return the ObservableValueInfo wrapping observableValue.
160   */
161  @Nonnull
162  <T> ObservableValueInfo asObservableValueInfo( @Nonnull ObservableValue<T> observableValue );
163
164  /**
165   * Convert the specified ComputableValue into an ComputableValueInfo.
166   *
167   * @param <T>             The type of the value that is computable.
168   * @param computableValue the ComputableValue.
169   * @return the ComputableValueInfo wrapping the ComputableValue.
170   */
171  @Nonnull
172  <T> ComputableValueInfo asComputableValueInfo( @Nonnull ComputableValue<T> computableValue );
173
174  /**
175   * Convert the specified task into an TaskInfo.
176   *
177   * @param task the Task.
178   * @return the TaskInfo.
179   */
180  @Nonnull
181  TaskInfo asTaskInfo( @Nonnull Task task );
182}