001package jmri.jmrix.zimo;
002
003/**
004 * Mx1Interface defines the general connection to a MX-1 layout.
005 * <p>
006 * Use this interface to send messages to a MX-1 layout. Classes implementing
007 * the Mx1Listener interface can register here to receive incoming MX-1 messages
008 * as events.
009 * <p>
010 * The jmri.jrmix.zimo.Mx1TrafficManager provides the first implementation of
011 * this interface.
012 * <p>
013 * How do you locate an implemenation of this interface? That's an interesting
014 * question. This is inherently MX-1 specific, so it would be inappropriate to
015 * put it in the jmri.InterfaceManager. And Java interfaces can't have static
016 * members, so we can't provide an implementation() member. For now, we use a
017 * static implementation member in the Mx1TrafficManager implementation to
018 * locate _any_ implementation; this clearly needs to be improved.
019 * <p>
020 * Mx1Listener implementations registering for traffic updates cannot assume
021 * that messages will be returned in any particular thread. See the Mx1Listener
022 * doc for more background.
023 *
024 * @author Bob Jacobsen Copyright (C) 2001, 2002
025 * @see jmri.jmrix.zimo.Mx1Listener
026 * @see jmri.jmrix.zimo.Mx1TrafficController
027 *
028 * Adapted by Sip Bosch for use with MX-1
029 *
030 */
031public interface Mx1Interface {
032
033    /*
034     * Request a message be sent to the attached MX-1. Return is immediate,
035     * with the message being queued for eventual sending.  If you're interested
036     * in a reply, you need to register a Mx1Listener object to watch the
037     * message stream. When sending, you specify (in 2nd parameter) who
038     * you are so you're not redundantly notified of this message.
039     */
040    void sendMx1Message(Mx1Message msg, Mx1Listener replyTo);
041
042    /**
043     * Request notification of things happening on the MX-1.
044     * <p>
045     * The same listener can register multiple times with different masks.
046     * (Multiple registrations with a single mask value are equivalent to a
047     * single registration) Mask values are defined as class constants. Note
048     * that these are bit masks, and should be OR'd, not added, if multiple
049     * values are desired.
050     * <p>
051     * The event notification contains the received message as source, not this
052     * object, so that we can notify of an incoming message to multiple places
053     * and then move on.
054     *
055     * @param mask     The OR of the key values of messages to be reported (to
056     *                 reduce traffic, provide for listeners interested in
057     *                 different things)
058     *
059     * @param listener Object to be notified of new messages as they arrive.
060     *
061     */
062    void addMx1Listener(int mask, Mx1Listener listener);
063
064    /*
065     * Stop notification of things happening on the MX-1. Note that mask and Mx1Listener
066     * must match a previous request exactly.
067     */
068    void removeMx1Listener(int mask, Mx1Listener listener);
069
070    /*
071     * Check whether an implementation is operational. True indicates OK.
072     */
073    boolean status();
074
075    /**
076     * Mask value to request notification of all incoming messages
077     */
078    int ALL = ~0;
079
080    /**
081     * Mask value to request notification of messages effecting slot status,
082     * including the programming slot
083     */
084    int SLOTINFO = 1;
085
086    /**
087     * Mask value to request notification of messages associated with
088     * programming
089     */
090    int PROGRAMMING = 2;
091
092    /**
093     * Mask value to request notification of messages indicating changes in
094     * turnout status
095     */
096    int TURNOUTS = 4;
097
098    /**
099     * Mask value to request notification of messages indicating changes in
100     * sensor status
101     */
102    int SENSORS = 8;
103
104    /**
105     * Mask value to request notification of messages associated with layout
106     * power
107     */
108    int POWER = 16;
109
110}
111
112
113