001package jmri.jmrix.loconet; 002 003/** 004 * LocoNetInterface defines the general connection to a LocoNet layout. 005 * <p> 006 * Use this interface to send messages to a LocoNet layout. Classes implementing 007 * the LocoNetListener interface can register here to receive incoming LocoNet 008 * messages as events. 009 * <p> 010 * The jmri.jrmix.loconet.LnTrafficController 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 LocoNet specific, so it would be inappropriate 015 * to 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 LnTrafficManager implementation to locate 018 * _any_ implementation; this clearly needs to be improved. 019 * <p> 020 * LocoNetListener implementations registering for traffic updates cannot assume 021 * that messages will be returned in any particular thread. See the 022 * LocoNetListener doc for more background. 023 * 024 * @author Bob Jacobsen Copyright (C) 2001 025 * @see jmri.jmrix.loconet.LocoNetListener 026 * @see jmri.jmrix.loconet.LnTrafficController 027 */ 028public interface LocoNetInterface { 029 030 /* 031 * Request a message be sent to the attached LocoNet. Return is immediate, 032 * with the message being queued for eventual sending. If you're interested 033 * in a reply, you need to register a LocoNetListener object to watch the 034 * message stream. 035 */ 036 void sendLocoNetMessage(LocoNetMessage msg); 037 038 /** 039 * Request notification of things happening on the LocoNet. 040 * <p> 041 * The same listener can register multiple times with different masks. 042 * (Multiple registrations with a single mask value are equivalent to a 043 * single registration) Mask values are defined as class constants. Note 044 * that these are bit masks, and should be OR'd, not added, if multiple 045 * values are desired. 046 * <p> 047 * The event notification contains the received message as source, not this 048 * object, so that we can notify of an incoming message to multiple places 049 * and then move on. 050 * 051 * @param mask The OR of the key values of messages to be reported (to 052 * reduce traffic, provide for listeners interested in 053 * different things) 054 * 055 * @param listener Object to be notified of new messages as they arrive. 056 * 057 */ 058 void addLocoNetListener(int mask, LocoNetListener listener); 059 060 /* 061 * Stop notification of things happening on the LocoNet. Note that mask and LocoNetListener 062 * must match a previous request exactly. 063 */ 064 void removeLocoNetListener(int mask, LocoNetListener listener); 065 066 /** 067 * Check whether an implementation is operational. Returns true if 068 * operational. 069 * 070 * @return true if implementation is operational. 071 */ 072 boolean status(); 073 074 /** 075 * Mask value to request notification of all incoming messages 076 */ 077 int ALL = ~0; 078 079 /** 080 * Mask value to request notification of messages effecting slot status, 081 * including the programming slot 082 */ 083 int SLOTINFO = 1; 084 085 /** 086 * Mask value to request notification of messages associated with 087 * programming 088 */ 089 int PROGRAMMING = 2; 090 091 /** 092 * Mask value to request notification of messages indicating changes in 093 * turnout status 094 */ 095 int TURNOUTS = 4; 096 097 /** 098 * Mask value to request notification of messages indicating changes in 099 * sensor status 100 */ 101 int SENSORS = 8; 102 103 /** 104 * Mask value to request notification of messages associated with layout 105 * power 106 */ 107 int POWER = 16; 108 109 /** 110 * Set the system connection memo associated with this connection. 111 * 112 * @param m associated systemConnectionMemo object 113 */ 114 void setSystemConnectionMemo(LocoNetSystemConnectionMemo m); 115 116 /** 117 * Get the system connection memo associated with this connection. 118 * 119 * @return the associated systemConnectionMemo object 120 */ 121 LocoNetSystemConnectionMemo getSystemConnectionMemo(); 122 123}