001package jmri.jmrit.logixng;
002
003import java.util.List;
004
005import javax.annotation.Nonnull;
006
007import jmri.JmriException;
008import jmri.NamedBean;
009import jmri.jmrit.logixng.SymbolTable.InitialValueType;
010import jmri.jmrit.logixng.SymbolTable.VariableData;
011
012import org.slf4j.Logger;
013
014/**
015 * A LogixNG male socket.
016 *
017 * @author Daniel Bergqvist Copyright 2018
018 */
019public interface MaleSocket extends Debugable {
020
021    public enum ErrorHandlingType {
022
023        Default(Bundle.getMessage("ErrorHandling_Default")),
024        ShowDialogBox(Bundle.getMessage("ErrorHandling_ShowDialogBox")),
025        LogError(Bundle.getMessage("ErrorHandling_LogError")),
026        LogErrorOnce(Bundle.getMessage("ErrorHandling_LogErrorOnce")),
027        ThrowException(Bundle.getMessage("ErrorHandling_ThrowException")),
028        AbortExecution(Bundle.getMessage("ErrorHandling_AbortExecution"));
029
030        private final String _description;
031
032        private ErrorHandlingType(String description) {
033            _description = description;
034        }
035
036        @Override
037        public String toString() {
038            return _description;
039        }
040    }
041
042    /**
043     * Set whenether this male socket is enabled or disabled.
044     * <P>
045     * This method must call registerListeners() / unregisterListeners().
046     *
047     * @param enable true if this male socket should be enabled, false otherwise
048     */
049    public void setEnabled(boolean enable);
050
051    /**
052     * Set whenether this male socket is enabled or disabled, without activating
053     * the male socket. This is used when loading the xml file and when copying
054     * an item.
055     * <P>
056     * This method must call registerListeners() / unregisterListeners().
057     *
058     * @param enable true if this male socket should be enabled, false otherwise
059     */
060    public void setEnabledFlag(boolean enable);
061
062    /**
063     * Determines whether this male socket is enabled.
064     *
065     * @return true if the male socket is enabled, false otherwise
066     */
067    @Override
068    public boolean isEnabled();
069
070    /**
071     * Get whenether the node should listen to changes or not.
072     * @return true if listen, false if not listen
073     */
074    public boolean getListen();
075
076    /**
077     * Set whenether the node should listen to changes or not.
078     * @param listen true if listen, false if not listen
079     */
080    public void setListen(boolean listen);
081
082    /**
083     * Is the node locked?
084     * @return true if locked, false otherwise
085     */
086    public boolean isLocked();
087
088    /**
089     * Set if the node is locked or not.
090     * @param locked true if locked, false otherwise
091     */
092    public void setLocked(boolean locked);
093
094    /**
095     * Is the node a system node?
096     * @return true if system, false otherwise
097     */
098    public boolean isSystem();
099
100    /**
101     * Set if the node is system or not.
102     * @param system true if system, false otherwise
103     */
104    public void setSystem(boolean system);
105
106    /**
107     * Is the node catching AbortExecution or not?
108     * @return true if catching, false otherwise
109     */
110    public boolean getCatchAbortExecution();
111
112    /**
113     * Set if the node should catch AbortExecution or not.
114     * @param catchAbortExecution true if catch, false otherwise
115     */
116    public void setCatchAbortExecution(boolean catchAbortExecution);
117
118    public void addLocalVariable(
119            String name,
120            InitialValueType initialValueType,
121            String initialValueData);
122
123    public void addLocalVariable(VariableData variableData);
124
125    public void clearLocalVariables();
126
127    public List<VariableData> getLocalVariables();
128
129    /**
130     * Get the error handling type for this socket.
131     * @return the error handling type
132     */
133    public ErrorHandlingType getErrorHandlingType();
134
135    /**
136     * Set the error handling type for this socket.
137     * @param errorHandlingType the error handling type
138     */
139    public void setErrorHandlingType(ErrorHandlingType errorHandlingType);
140
141    /**
142     * Handle an error that has happened during execution or evaluation of
143     * this item.
144     * @param  item           the item that had the error
145     * @param  message        the error message
146     * @param  e              the exception that has happened
147     * @param  log            the logger
148     * @throws JmriException  if the male socket is configured to
149     *                        throw an exception
150     */
151    public void handleError(
152            Base item,
153            String message,
154            JmriException e,
155            Logger log)
156            throws JmriException;
157
158    /**
159     * Handle an error that has happened during execution or evaluation of
160     * this item.
161     * @param  item           the item that had the error
162     * @param  message        the error message
163     * @param  messageList    a list of error messages
164     * @param  e              the exception that has happened
165     * @param  log            the logger
166     * @throws JmriException  if the male socket is configured to
167     *                        throw an exception
168     */
169    public void handleError(
170            Base item,
171            String message,
172            List<String> messageList,
173            JmriException e,
174            Logger log)
175            throws JmriException;
176
177    /**
178     * Handle an error that has happened during execution or evaluation of
179     * this item.
180     * @param  item           the item that had the error
181     * @param  message        the error message
182     * @param  e              the exception that has happened
183     * @param  log            the logger
184     * @throws JmriException  if the male socket is configured to
185     *                        throw an exception
186     */
187    public void handleError(
188            Base item,
189            String message,
190            RuntimeException e,
191            Logger log)
192            throws JmriException;
193
194    /**
195     * Get the object that this male socket holds.
196     * This method is used when the object is going to be configured.
197     *
198     * @return the object this male socket holds
199     */
200    @Nonnull
201    public Base getObject();
202
203    /**
204     * Get the manager that stores this socket.
205     * This method is used when the object is going to be configured.
206     *
207     * @return the manager
208     */
209    public BaseManager<? extends NamedBean> getManager();
210
211    /** {@inheritDoc} */
212    @Override
213    default public void setup() {
214        getObject().setup();
215    }
216
217    /**
218     * Find a male socket of a particular type.
219     * Male sockets can be stacked and this method travels thru the stacked
220     * male sockets to find the desired male socket.
221     * @param clazz the type of the male socket we are looking for
222     * @return the found male socket or null if not found
223     */
224    public default MaleSocket find(Class<?> clazz) {
225
226        if (! MaleSocket.class.isAssignableFrom(clazz)) {
227            throw new IllegalArgumentException("clazz is not a MaleSocket");
228        }
229
230        Base item = this;
231
232        while ((item instanceof MaleSocket) && !clazz.isInstance(item)) {
233            item = item.getParent();
234        }
235
236        if (clazz.isInstance(item)) return (MaleSocket)item;
237        else return null;
238    }
239
240}