View Javadoc

1   /*
2    *  
3    *  Fosstrak LLRP Commander (www.fosstrak.org)
4    * 
5    *  Copyright (C) 2008 ETH Zurich
6    *
7    *  This program is free software: you can redistribute it and/or modify
8    *  it under the terms of the GNU General Public License as published by
9    *  the Free Software Foundation, either version 3 of the License, or
10   *  (at your option) any later version.
11   *
12   *  This program is distributed in the hope that it will be useful,
13   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
14   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   *  GNU General Public License for more details.
16   *
17   *  You should have received a copy of the GNU General Public License
18   *  along with this program.  If not, see <http://www.gnu.org/licenses/> 
19   *
20   */
21  
22  package org.fosstrak.llrp.adaptor;
23  
24  import java.rmi.Remote;
25  import java.rmi.RemoteException;
26  
27  import org.fosstrak.llrp.adaptor.exception.LLRPRuntimeException;
28  
29  /**
30   * This class models a logical entity of a physical reader. it maintains 
31   * the connectivity to the physical reader. 
32   * @author sawielan
33   *
34   */
35  public interface Reader extends Remote  {
36  
37  	/**
38  	 * connects this reader to the real physical llrp reader.
39  	 * @param clientInitiatedConnection if the connection is initiated by the client then 
40  	 * you should pass true. if the physical reader initiates the connection then provide false.
41  	 * @throws LLRPRuntimeException whenever an error occurs.
42  	 * @throws RemoteException whenever there is an rmi error.
43  	 */
44  	public void connect(boolean clientInitiatedConnection)
45  			throws LLRPRuntimeException, RemoteException;
46  
47  	/**
48  	 * disconnect the reader stub from the physical reader.
49  	 * @throws RemoteException whenever there is an rmi error.
50  	 */
51  	public void disconnect() throws RemoteException;
52  
53  	/**
54  	 * try to reconnect the reader.
55  	 * @throws RemoteException whenever there is an rmi error.
56  	 * @throws LLRPRuntimeException whenever there is a exception during connection setup.
57  	 */
58  	public void reconnect() throws LLRPRuntimeException, RemoteException;
59  
60  	/**
61  	 * send a message to the llrp reader.
62  	 * @param message the message to be sent.
63  	 * @throws RemoteException whenever there is an rmi error.
64  	 */
65  	public void send(byte[] message) throws RemoteException;
66  
67  	/**
68  	 * tells if the reader is connected or not.
69  	 * @return true if the reader is connected.
70  	 * @throws RemoteException whenever there is an rmi error.
71  	 */
72  	public boolean isConnected() throws RemoteException;
73  
74  	/**
75  	 * return the ip address of this reader.
76  	 * @return the ip address of this reader.
77  	 * @throws RemoteException whenever there is an rmi error.
78  	 */
79  	public String getReaderAddress() throws RemoteException;
80  
81  	/**
82  	 * return the name of this reader.
83  	 * @return the name of this reader.
84  	 * @throws RemoteException whenever there is an rmi error.
85  	 */
86  	public String getReaderName() throws RemoteException;
87  	
88  	/**
89  	 * return the port of this reader.
90  	 * @return the port of this reader.
91  	 * @throws RemoteException whenever there is an rmi error.
92  	 */
93  	public int getPort() throws RemoteException;
94  
95  	/**
96  	 * tell if this reader maintains a client initiated connection or if the 
97  	 * reader accepts a connection from a llrp reader.
98  	 * @return <ul><li>true if client initiated connection</li><li>false if llrp reader initiated connection</li></ul>
99  	 * @throws RemoteException whenever there is an rmi error.
100 	 */
101 	public boolean isClientInitiated() throws RemoteException;
102 
103 	/**
104 	 * sets the connect behavior to the specified value.
105 	 * @param clientInitiated if true then the client issues the connect.
106 	 * @throws RemoteException whever there is an RMI error.
107 	 */
108 	public void setClientInitiated(boolean clientInitiated) throws RemoteException;
109 	
110 	/** 
111 	 * tells whether this reader connects immediately after creation.
112 	 * @return whether this reader connects immediately after creation.
113 	 * @throws RemoteException whenever there is an RMI error.
114 	 */
115 	public boolean isConnectImmediate() throws RemoteException;
116 	
117 	/**
118 	 * 
119 	 * tells whether this reader connects immediately after creation.
120 	 * @param value whether this reader connects immediately after creation.
121 	 * @throws RemoteException whenever there is an RMI error.	 
122 	 */
123 	public void setConnectImmediate(boolean value) throws RemoteException;
124 	
125 	/**
126 	 * register for asynchronous messages from the physical reader.
127 	 * @param receiver the receiver that shall be notified with the message.
128 	 * @throws RemoteException whenever there is an RMI error.
129 	 */
130 	public abstract void registerForAsynchronous(AsynchronousNotifiable receiver) throws RemoteException;
131 
132 	/**
133 	 * deregister from the asynchronous messages. the receiver will no more 
134 	 * receive asynchronous llrp messages.
135 	 * @param receiver the receiver to deregister.
136 	 * @throws RemoteException whenever there is an RMI error.
137 	 */
138 	public void deregisterFromAsynchronous(
139 			AsynchronousNotifiable receiver) throws RemoteException;
140 	
141 	/**
142 	 * sets the connection timeout period for the reader. if the times * keepAlivePeriod has 
143 	 * passed by without a notification from the reader the reader gets disconnected.
144 	 * @param keepAlivePeriod the reader must send in this period a keepalive message. time in ms.
145 	 * @param times how many missed keepalive messages are ok.
146 	 * @param report whether to report the keepalive messages to the repo or not.
147 	 * @param throwException whether to throw an exception upon disconnection.
148 	 * @throws RemoteException whenever there is an RMI error. 
149 	 */
150 	public void setKeepAlivePeriod(int keepAlivePeriod, int times, boolean report, boolean throwException) throws RemoteException;
151 	
152 	/**
153 	 * returns the keepalive period set for this reader.
154 	 * @return the keepalive period set for this reader.
155 	 * @throws RemoteException whenever there is an RMI error. 
156 	 */
157 	public int getKeepAlivePeriod() throws RemoteException;
158 	
159 	/**
160 	 * if set to true, the reader will report all the keep-alive messages exchanged between the 
161 	 * reader and the driver stub.
162 	 * @param report if true report the status messages. if false not.
163 	 * @throws RemoteException whenever there is an RMI error.
164 	 */
165 	public void setReportKeepAlive(boolean report) throws RemoteException;
166 	
167 	/**
168 	 * @return whether the reader stub delivers the keep-alive messages to the repo or not.
169 	 * @throws RemoteException whenever there is an RMI error.
170 	 */
171 	public boolean isReportKeepAlive() throws RemoteException;
172 	
173 	/**
174 	 * the reader meta-data contains information about the reader, the settings, etc.
175 	 * @return a meta-data structure.
176 	 * @throws RemoteException whenever there is an RMI error.
177 	 */
178 	public ReaderMetaData getMetaData() throws RemoteException;
179 }