PageRenderTime 47ms CodeModel.GetById 16ms RepoModel.GetById 0ms app.codeStats 0ms

/Source/DataTurbine/com/rbnb/api/Address.java

http://dataturbine.googlecode.com/
Java | 558 lines | 97 code | 31 blank | 430 comment | 7 complexity | 94a69fa046335a35a6fcf3074ea5fffc MD5 | raw file
Possible License(s): Apache-2.0, LGPL-2.1, BSD-3-Clause, GPL-2.0
  1. /*
  2. Copyright 2007 Creare Inc.
  3. Licensed under the Apache License, Version 2.0 (the "License");
  4. you may not use this file except in compliance with the License.
  5. You may obtain a copy of the License at
  6. http://www.apache.org/licenses/LICENSE-2.0
  7. Unless required by applicable law or agreed to in writing, software
  8. distributed under the License is distributed on an "AS IS" BASIS,
  9. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  10. See the License for the specific language governing permissions and
  11. limitations under the License.
  12. */
  13. package com.rbnb.api;
  14. /**
  15. * Abstract class that deals with RBNB server addresses.
  16. * <p>
  17. * RBNB server addresses serve as the means by which a client application using
  18. * the API connects to the RBNB DataTurbine server. They represent the
  19. * server's address and provide an abstraction of the details of communicating
  20. * over that sort of address.
  21. * <p>
  22. * The files are organized into a hierarchy as follows:
  23. * <p>
  24. * <dir><code>Address</code>
  25. * <dir><code>TCP</code></dir>
  26. * <dir><code>RAM</code>
  27. * <dir>Adjunct classes: <code>RAMCommunications</code> and
  28. * <code>RAMServerCommunications</code></dir>
  29. * </dir>
  30. * </dir>
  31. * <p>
  32. * The <code>Address</code> class provides the external interface for using
  33. * addresses.
  34. * <p>
  35. * The <code>TCP</code> class provides the low-level TCP socket handling
  36. * methods for using TCP server sockets as the address of an RBNB DataTurbine
  37. * server.
  38. * <p>
  39. * The <code>RAM</code> class provides the low-level in-memory (RAM) handling
  40. * methods for using direct memory-to-memory copy to communicate between the
  41. * API and the RBNB DataTurbine server.
  42. * <p>
  43. * The <code>RAMCommunications</code> adjunct class provides the client side
  44. * handling of the memory-to-memory copies. It is the RAM equivalent of a
  45. * standard TCP socket.
  46. * <p>
  47. * The <code>RAMServerCommunications</code> adjunct class provides the server
  48. * side handling of the memory-to-memory copies. It is the RAM equivalent of a
  49. * TCP server socket.
  50. * <p>
  51. *
  52. * @author Ian Brown
  53. *
  54. * @since V2.0
  55. * @version 08/06/2004
  56. */
  57. /*
  58. * Copyright 2001, 2002, 2004 Creare Inc.
  59. * All Rights Reserved
  60. *
  61. * Date By Description
  62. * MM/DD/YYYY
  63. * ---------- -- -----------
  64. * 2005/01/20 WHF Now implements UsernameInterface.
  65. * 08/06/2004 INB Added documentation.
  66. * 05/11/2001 INB Created.
  67. *
  68. */
  69. abstract class Address implements UsernameInterface {
  70. /**
  71. * the address being handled.
  72. * <p>
  73. *
  74. * @author Ian Brown
  75. *
  76. * @since V2.0
  77. * @version 05/11/2001
  78. */
  79. private String address = null;
  80. /**
  81. * the authorization list to check incoming addresses against.
  82. * <p>
  83. *
  84. * @author Ian Brown
  85. *
  86. * @since V2.0
  87. * @version 10/18/2002
  88. */
  89. private AddressAuthorization authorization = null;
  90. private Username username;
  91. /**
  92. * Class constructor.
  93. * <p>
  94. *
  95. * @author Ian Brown
  96. *
  97. * @since V2.0
  98. * @version 05/11/2001
  99. */
  100. /*
  101. *
  102. * Date By Description
  103. * MM/DD/YYYY
  104. * ---------- -- -----------
  105. * 05/11/2001 INB Created.
  106. *
  107. */
  108. Address() {
  109. super();
  110. }
  111. /**
  112. * Class constructor to build an <code>Address</code> for an address.
  113. * <p>
  114. *
  115. * @author Ian Brown
  116. *
  117. * @param addressI the TCP DNS or IP address.
  118. * @exception com.rbnb.api.AddressException
  119. * thrown if there is a problem with the address.
  120. * @since V2.0
  121. * @version 05/11/2001
  122. */
  123. /*
  124. *
  125. * Date By Description
  126. * MM/DD/YYYY
  127. * ---------- -- -----------
  128. * 05/11/2001 INB Created.
  129. *
  130. */
  131. Address(String addressI)
  132. throws com.rbnb.api.AddressException
  133. {
  134. this();
  135. setAddress(addressI);
  136. }
  137. /**
  138. * Accepts connections to a server-side connection object.
  139. * <p>
  140. *
  141. * @author Ian Brown
  142. *
  143. * @param serverSideI the server-side connection object.
  144. * @param timeOutI timeout in milliseconds.
  145. * <br><ul>
  146. * <li><code>Client.FOREVER</code> means wait for a
  147. * response to show up, or</li>
  148. * <li>anything else means wait for a response to show up
  149. * or for the timeout period to elapse.</li>
  150. * </ul>
  151. * @return the connection object.
  152. * @exception java.io.IOException
  153. * thrown if there is an I/O problem.
  154. * @exception java.lang.InterruptedException
  155. * thrown if the operation is interrupted.
  156. * @exception com.rbnb.api.AddressException
  157. * thrown if the address is rejected for any reason.
  158. * @see #connect(java.lang.Object)
  159. * @since V2.0
  160. * @version 10/18/2002
  161. */
  162. /*
  163. *
  164. * Date By Description
  165. * MM/DD/YYYY
  166. * ---------- -- -----------
  167. * 05/11/2001 INB Created.
  168. *
  169. */
  170. abstract Object accept(Object serverSideI,long timeOutI)
  171. throws com.rbnb.api.AddressException,
  172. java.io.IOException,
  173. java.lang.InterruptedException;
  174. /**
  175. * Closes a connection object for this <code>Address</code>.
  176. * <p>
  177. *
  178. * @author Ian Brown
  179. *
  180. * @param connectionI the connection object.
  181. * @since V2.0
  182. * @version 03/18/2002
  183. */
  184. /*
  185. *
  186. * Date By Description
  187. * MM/DD/YYYY
  188. * ---------- -- -----------
  189. * 05/15/2001 INB Created.
  190. *
  191. */
  192. abstract void close(Object connectionI);
  193. /**
  194. * Connects to the RBNB server.
  195. * <p>
  196. *
  197. * @author Ian Brown
  198. *
  199. * @param clientSideI the client-side object.
  200. * @exception java.io.IOException
  201. * thrown if there is an I/O problem.
  202. * @exception java.lang.InterruptedException
  203. * thrown if the operation is interrupted.
  204. * @see #accept(java.lang.Object,long)
  205. * @see #disconnect(java.lang.Object)
  206. * @since V2.0
  207. * @version 03/18/2002
  208. */
  209. /*
  210. *
  211. * Date By Description
  212. * MM/DD/YYYY
  213. * ---------- -- -----------
  214. * 05/11/2001 INB Created.
  215. *
  216. */
  217. abstract void connect(Object clientSideI)
  218. throws java.io.IOException,
  219. java.lang.InterruptedException;
  220. /**
  221. * Disconnects from the RBNB server.
  222. * <p>
  223. *
  224. * @author Ian Brown
  225. *
  226. * @param clientSideI the client-side object.
  227. * @exception java.io.IOException
  228. * thrown if there is an I/O problem.
  229. * @exception java.lang.InterruptedException
  230. * thrown if the operation is interrupted.
  231. * @see #accept(java.lang.Object,long)
  232. * @since V2.0
  233. * @version 03/18/2002
  234. */
  235. /*
  236. *
  237. * Date By Description
  238. * MM/DD/YYYY
  239. * ---------- -- -----------
  240. * 05/11/2001 INB Created.
  241. *
  242. */
  243. abstract void disconnect(Object clientSideI)
  244. throws java.io.IOException,
  245. java.lang.InterruptedException;
  246. /**
  247. * Gets the address being handled.
  248. * <p>
  249. *
  250. * @author Ian Brown
  251. *
  252. * @return the address.
  253. * @see #setAddress(String)
  254. * @since V2.0
  255. * @version 05/22/2001
  256. */
  257. /*
  258. *
  259. * Date By Description
  260. * MM/DD/YYYY
  261. * ---------- -- -----------
  262. * 05/11/2001 INB Created.
  263. *
  264. */
  265. final String getAddress() {
  266. return (address);
  267. }
  268. /**
  269. * Gets the authorization list.
  270. * <p>
  271. *
  272. * @author Ian Brown
  273. *
  274. * @return the authorization list.
  275. * @see #setAuthorization(com.rbnb.api.AddressAuthorization)
  276. * @since V2.0
  277. * @version 10/18/2002
  278. */
  279. /*
  280. *
  281. * Date By Description
  282. * MM/DD/YYYY
  283. * ---------- -- -----------
  284. * 10/18/2002 INB Created.
  285. *
  286. */
  287. final AddressAuthorization getAuthorization() {
  288. return (authorization);
  289. }
  290. /**
  291. * Is the address one that can be handled by a local RBNB server?
  292. * <p>
  293. *
  294. * @author Ian Brown
  295. *
  296. * @return is the address local?
  297. * @since V2.0
  298. * @version 05/11/2001
  299. */
  300. /*
  301. *
  302. * Date By Description
  303. * MM/DD/YYYY
  304. * ---------- -- -----------
  305. * 05/11/2001 INB Created.
  306. * 2007/11/26 WHF Removed, as was unused and may be difficult to determine
  307. * with some address types.
  308. *
  309. */
  310. //abstract boolean isLocal();
  311. /**
  312. * Creates a new <code>Address</code> to handle the specified address.
  313. * <p>
  314. *
  315. * @author Ian Brown
  316. *
  317. * @param addressI the address to handle.
  318. * @return the <code>Address</code> object for handling the address.
  319. * @exception com.rbnb.api.AddressException
  320. * thrown if there is a problem with the address.
  321. * @since V2.0
  322. * @version 08/06/2004
  323. */
  324. /*
  325. *
  326. * Date By Description
  327. * MM/DD/YYYY
  328. * ---------- -- -----------
  329. * 08/06/2004 INB Added some in-line documentation.
  330. * 05/11/2001 INB Created.
  331. *
  332. */
  333. final static Address newAddress(String addressI)
  334. throws com.rbnb.api.AddressException
  335. {
  336. int ss = addressI.indexOf("//");
  337. Address addressR = null;
  338. if (ss == -1) {
  339. // If the address does not include //, then assume that it is a TCP
  340. // address.
  341. addressR = new TCP(TCP.buildAddress(addressI));
  342. } else {
  343. // Otherwise, determine the type of address from the string
  344. // preceeding the //.
  345. String type = addressI.substring(0,ss);
  346. if (type.equalsIgnoreCase("RAM:") ||
  347. type.equalsIgnoreCase("INTERNAL:")) {
  348. // RAM and INTERNAL addresses use the RAM class for in-memory
  349. // thread to thread communications.
  350. addressR = new RAM(addressI);
  351. } else if (type.equalsIgnoreCase("TCP:")) {
  352. // TCP addresses use the TCP class for TCP socket to server
  353. // socket communications.
  354. addressR = new TCP(TCP.buildAddress(addressI));
  355. } else {
  356. throw new com.rbnb.api.AddressException
  357. ("Unsupported address: " + addressI);
  358. }
  359. }
  360. return (addressR);
  361. }
  362. /**
  363. * Creates a new client-side connection to the address.
  364. * <p>
  365. *
  366. * @author Ian Brown
  367. *
  368. * @param acoI the <code>ACO</code>.
  369. * @return the connection object.
  370. * @exception com.rbnb.api.AddressException
  371. * thrown if there is a problem creating the connection.
  372. * @exception java.io.IOException
  373. * thrown if there is an I/O problem creating the connection.
  374. * @exception java.lang.SecurityException
  375. * thrown if the security manager refuses the connection.
  376. * @see #newServerSide(com.rbnb.api.ServerHandler)
  377. * @since V2.0
  378. * @version 05/14/2001
  379. */
  380. /*
  381. *
  382. * Date By Description
  383. * MM/DD/YYYY
  384. * ---------- -- -----------
  385. * 05/11/2001 INB Created.
  386. *
  387. */
  388. abstract Object newClientSide(ACO acoI)
  389. throws com.rbnb.api.AddressException,
  390. java.io.IOException,
  391. java.lang.SecurityException;
  392. /**
  393. * Creates a new server-side connection to the address.
  394. * <p>
  395. *
  396. * @author Ian Brown
  397. *
  398. * @param serverHandlerI the <code>ServerHandler</code>.
  399. * @return the connection object.
  400. * @exception com.rbnb.api.AddressException
  401. * thrown if there is a problem creating the connection.
  402. * @exception java.io.IOException
  403. * thrown if there is an I/O problem creating the connection.
  404. * @exception java.lang.SecurityException
  405. * thrown if the security manager refuses the connection.
  406. * @see #newClientSide(com.rbnb.api.ACO)
  407. * @since V2.0
  408. * @version 05/11/2001
  409. */
  410. /*
  411. *
  412. * Date By Description
  413. * MM/DD/YYYY
  414. * ---------- -- -----------
  415. * 05/11/2001 INB Created.
  416. *
  417. */
  418. abstract Object newServerSide(ServerHandler serverHandlerI)
  419. throws com.rbnb.api.AddressException,
  420. java.io.IOException,
  421. java.lang.SecurityException;
  422. /**
  423. * Sets the address to handle.
  424. * <p>
  425. *
  426. * @author Ian Brown
  427. *
  428. * @param addressI the address.
  429. * @exception com.rbnb.api.AddressException
  430. * thrown if the address is not valid.
  431. * @see #getAddress()
  432. * @since V2.0
  433. * @version 05/11/2001
  434. */
  435. /*
  436. *
  437. * Date By Description
  438. * MM/DD/YYYY
  439. * ---------- -- -----------
  440. * 05/11/2001 INB Created.
  441. *
  442. */
  443. void setAddress(String addressI)
  444. throws com.rbnb.api.AddressException
  445. {
  446. address = addressI;
  447. }
  448. /**
  449. * @author WHF
  450. * @since V2.5
  451. */
  452. public Username getUsername() { return username; }
  453. /**
  454. * @author WHF
  455. * @since V2.5
  456. */
  457. public void setUsername(Username un) { username = un; }
  458. /**
  459. * Sets the address authorization list.
  460. * <p>
  461. *
  462. * @author Ian Brown
  463. *
  464. * @param authorizationI the address authorization list.
  465. * @see #getAuthorization()
  466. * @since V2.0
  467. * @version 10/18/2002
  468. */
  469. /*
  470. *
  471. * Date By Description
  472. * MM/DD/YYYY
  473. * ---------- -- -----------
  474. * 10/18/2002 INB Created.
  475. *
  476. */
  477. final void setAuthorization(AddressAuthorization authorizationI) {
  478. authorization = authorizationI;
  479. }
  480. /**
  481. * Returns a string representation of this <code>Address</code>.
  482. * <p>
  483. *
  484. * @author Ian Brown
  485. *
  486. * @return the string representation.
  487. * @since V2.0
  488. * @version 05/16/2001
  489. */
  490. /*
  491. *
  492. * Date By Description
  493. * MM/DD/YYYY
  494. * ---------- -- -----------
  495. * 05/16/2001 INB Created.
  496. *
  497. */
  498. public String toString() {
  499. String stringR = null;
  500. try {
  501. String className = getClass().toString();
  502. className = className.substring
  503. (className.lastIndexOf(".") + 1);
  504. stringR = className + " " + getAddress();
  505. } catch (java.lang.Exception e) {
  506. }
  507. return (stringR);
  508. }
  509. }