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 import java.util.List;
27
28 import org.fosstrak.llrp.adaptor.exception.LLRPRuntimeException;
29
30 /**
31 * The interface Adaptor provides a general interface how to
32 * access a set of LLRP readers.
33 * @author sawielan
34 *
35 */
36 public interface Adaptor extends Remote {
37 /**
38 * defines a new LLRP reader on this adaptor.
39 * @param readerName the name of the LLRP reader.
40 * @param readerAddress the address where to contact the LLRP reader.
41 * @param clientInitiatedConnection LLRP allows two different ways how to create a connection to
42 * a reader. <br/>
43 * <ol>
44 * <li>client initiated connection: in this model the client tries to establish the connection to the reader</li>
45 * <li>reader initiated connection: in this model the client waits for a reader to establish the connection</li>
46 * </ol>
47 * when you specify true a client initiated connection is established. otherwise a reader initiated connection.
48 * @param connectImmediately tells whether the reader shall establish connection immediately or not<br/>
49 * <ol>
50 * <li>true: the reader tries to build up the connection immediately</li>
51 * <li>false: the reader is just created, but the connection to the physical reader will not be established yet.
52 * you need to run the connect command on the reader before you can use it!</li>
53 * </ol>
54 * @throws LLRPRuntimeException if a runtime exception occurs (like duplicate reader name etc. ...).
55 * @throws RemoteException when there was an rmi exception.
56 */
57 public void define(String readerName,
58 String readerAddress,
59 boolean clientInitiatedConnection,
60 boolean connectImmediately) throws RemoteException, LLRPRuntimeException;
61
62 /**
63 * defines a new LLRP reader on this adaptor.
64 * @param readerName the name of the LLRP reader.
65 * @param readerAddress the address where to contact the LLRP reader.
66 * @param port the port where to connect to.
67 * @param clientInitiatedConnection LLRP allows two different ways how to create a connection to
68 * a reader. <br/>
69 * <ol>
70 * <li>client initiated connection: in this model the client tries to establish the connection to the reader</li>
71 * <li>reader initiated connection: in this model the client waits for a reader to establish the connection</li>
72 * </ol>
73 * when you specify true a client initiated connection is established. otherwise a reader initiated connection.
74 * @param connectImmediately tells whether the reader shall establish connection immediately or not<br/>
75 * <ol>
76 * <li>true: the reader tries to build up the connection immediately</li>
77 * <li>false: the reader is just created, but the connection to the physical reader will not be established yet.
78 * you need to run the connect command on the reader before you can use it!</li>
79 * </ol>
80 * @throws LLRPRuntimeException if a runtime exception occurs (like duplicate reader name etc. ...).
81 * @throws RemoteException when there was an rmi exception.
82 */
83 public void define(String readerName,
84 String readerAddress,
85 int port,
86 boolean clientInitiatedConnection,
87 boolean connectImmediately) throws RemoteException, LLRPRuntimeException;
88
89 /**
90 * removes a LLRP reader from this adaptor.
91 * @param readerName the name of the LLRP reader to remove.
92 * @throws LLRPRuntimeException if a runtime exception occurs (eg reader does not exist etc. ...).
93 * @throws RemoteException when there was an rmi exception.
94 */
95 public void undefine(String readerName) throws RemoteException, LLRPRuntimeException;
96
97 /**
98 * removes all the LLRP readers from this adaptor.
99 * @throws RemoteException when there was an rmi exception.
100 * @throws LLRPRuntimeException if a runtime exception occurs (eg reader does not exist etc. ...).
101 */
102 public void undefineAll() throws RemoteException, LLRPRuntimeException;
103
104 /**
105 * disconnects all the LLRP readers from this adaptor.
106 * @throws RemoteException when there was an rmi exception.
107 * @throws LLRPRuntimeException if a runtime exception occurs (eg reader does not exist etc. ...).
108 */
109 public void disconnectAll() throws RemoteException, LLRPRuntimeException;
110
111 /**
112 * checks whether a readerName already exists.
113 * @param readerName the name of the reader.
114 * @return true if the reader exists else false.
115 * @throws RemoteException when there was an rmi exception.
116 */
117 public boolean containsReader(String readerName) throws RemoteException;
118
119 /**
120 * returns a list of all currently registered LLRP readers.
121 * @return a list of all currently registered LLRP readers.
122 * @throws RemoteException when there was an rmi exception.
123 */
124 public List<String> getReaderNames() throws RemoteException;
125
126 /**
127 * returns a requested reader.
128 * @param readerName the name of the requested reader.
129 * @return the reader.
130 * @throws RemoteException when there was an rmi exception.
131 */
132 public Reader getReader(String readerName) throws RemoteException;
133
134 /**
135 * returns the name of this adaptor.
136 * @return the name of this adaptor.
137 * @throws RemoteException when there was an rmi exception.
138 */
139 public String getAdaptorName() throws RemoteException;
140
141 /**
142 * sets the name of the adaptor.
143 * @param adaptorName the name of the adaptor to set.
144 * @throws RemoteException
145 */
146 public void setAdaptorName(String adaptorName) throws RemoteException;
147 /**
148 * sends a llrp message to the specified reader.
149 * @param readerName the name of the reader where to send the message.
150 * @param message the llrp message.
151 * @throws LLRPRuntimeException whever a runtime error occurs.
152 * @throws RemoteException when there was an rmi exception.
153 */
154 public void sendLLRPMessage(String readerName, byte[] message) throws RemoteException, LLRPRuntimeException;
155
156 /**
157 * sends a llrp message to all the readers.
158 * @param message the llrp message.
159 * @throws LLRPRuntimeException whever a runtime error occurs.
160 * @throws RemoteException when there was an rmi exception.
161 */
162 public void sendLLRPMessageToAllReaders(byte[] message) throws RemoteException, LLRPRuntimeException;
163
164 /**
165 * register for asynchronous messages from the reader.
166 * @param receiver the receiver that shall be notified with the message.
167 * @throws RemoteException when there was an rmi exception.
168 */
169 public void registerForAsynchronous(AsynchronousNotifiable receiver) throws RemoteException;
170
171 /**
172 * deregister from the asynchronous messages. the receiver will no more
173 * receive asynchronous llrp messages.
174 * @param receiver the receiver to deregister.
175 * @throws RemoteException when there was an rmi exception.
176 */
177 public void deregisterFromAsynchronous(AsynchronousNotifiable receiver) throws RemoteException;
178
179 /**
180 * when a asynchronous message arrives from the reader this method
181 * will be invoked. the message then gets dispatched to the
182 * registered receivers.
183 * @param message the llrp message.
184 * @param readerName the name of the reader that triggered the event.
185 * @throws RemoteException when there was an rmi exception.
186 */
187 public void messageReceivedCallback(byte[] message, String readerName) throws RemoteException;
188
189 /**
190 * callback interface for asynchronous error messages from the reader.
191 * @param e the exception that has been reported.
192 * @param readerName the name of the reader where the error occured.
193 * @throws RemoteException whenver there is an error on transport level (rmi).
194 */
195 public void errorCallback(LLRPRuntimeException e, String readerName) throws RemoteException;
196
197 }