001package jmri.jmrix.lenz;
002
003/**
004 * XNetInterface defines the general connection to an XNet layout.
005 * <p>
006 * Use this interface to send messages to an XNet layout. Classes implementing
007 * the XNetListener interface can register here to receive incoming XNet
008 * messages as events.
009 * <p>
010 * The jmri.jrmix.lenz.XNetTrafficControler 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 XNet 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 XNetTrafficController implementation to
018 * locate _any_ implementation; this clearly needs to be improved.
019 * <p>
020 * XNetListener implementations registering for traffic updates cannot assume
021 * that messages will be returned in any particular thread. See the XNetListener
022 * doc for more background.
023 *
024 * @author Bob Jacobsen Copyright (C) 2001, 2002
025 * @see jmri.jmrix.lenz.XNetListener
026 * @see jmri.jmrix.lenz.XNetTrafficController
027 */
028public interface XNetInterface {
029
030    /**
031     * Request a message be sent to the attached XNet. Return is immediate,
032     * with the message being queued for eventual sending.  If you're interested
033     * in a reply, you need to register an XNetListener object to watch the
034     * message stream. When sending, you specify (in 2nd parameter) who
035     * you are so you're not redundantly notified of this message.
036     * @param msg the XNet message to send.
037     * @param replyTo sending listener to NOT notify.
038     */
039    void sendXNetMessage(XNetMessage msg, XNetListener replyTo);
040
041    /**
042     * Request notification of things happening on the XNet.
043     * <p>
044     * The same listener can register multiple times with different masks.
045     * (Multiple registrations with a single mask value are equivalent to a
046     * single registration) Mask values are defined as class constants. Note
047     * that these are bit masks, and should be OR'd, not added, if multiple
048     * values are desired.
049     * <p>
050     * The event notification contains the received message as source, not this
051     * object, so that we can notify of an incoming message to multiple places
052     * and then move on.
053     *
054     * @param mask The OR of the key values of messages to be reported (to
055     *             reduce traffic, provide for listeners interested in different
056     *             things)
057     *
058     * @param l    Object to be notified of new messages as they arrive.
059     *
060     */
061    void addXNetListener(int mask, XNetListener l);
062
063    /**
064     * Stop notification of things happening on the XNet.
065     * <p>
066     * Note that mask and XNetListener must match a previous request exactly.
067     * @param mask listening mask.
068     * @param listener listener to remove notifications for. 
069     */
070    void removeXNetListener(int mask, XNetListener listener);
071
072    /**
073     * Check whether an implementation is operational.
074     * @return true if OK, else false.
075     */
076    boolean status();
077
078    /**
079     * Mask value to request notification of all incoming messages
080     */
081    int ALL = ~0;
082
083    /**
084     * Mask value to request notification of communications related messages
085     * generated by the computer interface
086     */
087    int COMMINFO = 1;
088
089    /**
090     * Mask value to request notification of Command Station informational
091     * messages This includes all broadcast messages, except for the feedback
092     * broadcast and all programming messages
093     */
094    int CS_INFO = 2;
095
096    /**
097     * Mask value to request notification of messages associated with
098     * programming
099     */
100    int PROGRAMMING = 4;
101
102    /**
103     * Mask value to request notification of XpressNet FeedBack (i.e. sensor)
104     * related messages
105     */
106    int FEEDBACK = 8;
107
108    /**
109     * Mask value to request notification of messages associated with throttle
110     * status
111     *
112     */
113    int THROTTLE = 16;
114
115    /**
116     * Mask value to request notification of messages associated with consists
117     *
118     */
119    int CONSIST = 32;
120
121    /**
122     * Mask value to request notification of messages associated with the interface
123     *
124     */
125    int INTERFACE = 64;
126
127}