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}