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}