1 package org.djutils.rmi;
2
3 import java.net.URL;
4 import java.rmi.AccessException;
5 import java.rmi.AlreadyBoundException;
6 import java.rmi.RemoteException;
7 import java.rmi.registry.Registry;
8 import java.rmi.server.UnicastRemoteObject;
9
10 import org.djutils.exceptions.Throw;
11
12 /**
13 * The RMIObject is an object that registers iteself in the RMI registry using a key by which it can be found. The class creates
14 * the RMI registry when it does not exist yet.
15 * <p>
16 * Copyright (c) 2020-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
17 * BSD-style license. See <a href="https://djutils.org/docs/license.html">DJUTILS License</a>.
18 * </p>
19 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a>
20 */
21 public class RmiObject extends UnicastRemoteObject
22 {
23 /** */
24 private static final long serialVersionUID = 20200111L;
25
26 /** pointer to the registry in which the object has been registered to look up other objects. */
27 private Registry registry;
28
29 /**
30 * Register this object in the RMI registry. When the host has not been specified in the URL, 127.0.0.1 will be used. When
31 * the port has not been specified in the URL, the default RMI port 1099 will be used. When the RMI registry does not exist
32 * yet, it will be created, but <b>only</b> on the local host. Remote creation of a registry on another computer is not
33 * possible. Any attempt to do so will cause an AccessException to be fired.
34 * @param registryURL URL; the URL of the registry, e.g., "http://localhost:1099" or "http://130.161.185.14:28452"
35 * @param bindingKey String; the key under which this object will be bound in the RMI registry
36 * @throws RemoteException when there is a problem with the RMI registry
37 * @throws AlreadyBoundException when there is already another object bound to the bindingKey
38 * @throws NullPointerException when registryURL or bindingKey is null
39 * @throws AccessException when there is an attempt to create a registry on a remote host
40 */
41 public RmiObject(final URL registryURL, final String bindingKey) throws RemoteException, AlreadyBoundException
42 {
43 Throw.whenNull(registryURL, "registryURL cannot be null");
44 Throw.whenNull(bindingKey, "bindingKey cannot be null");
45 String host = registryURL.getHost() == null ? "127.0.0.1" : registryURL.getHost();
46 int port = registryURL.getPort() == -1 ? 1099 : registryURL.getPort();
47 register(host, port, bindingKey);
48 }
49
50 /**
51 * Register this object in the RMI registry. When the RMI registry does not exist yet, it will be created, but <b>only</b>
52 * on the local host. Remote creation of a registry on another computer is not possible. Any attempt to do so will cause an
53 * AccessException to be fired.
54 * @param host String; the host where the RMI registry resides or will be created. Creation is only possible on localhost.
55 * @param port int; the port where the RMI registry can be found or will be created
56 * @param bindingKey String; the key under which this object will be bound in the RMI registry
57 * @throws RemoteException when there is a problem with the RMI registry
58 * @throws AlreadyBoundException when there is already another object bound to the bindingKey
59 * @throws NullPointerException when host, path, or bindingKey is null
60 * @throws IllegalArgumentException when port < 0 or port > 65535
61 * @throws AccessException when there is an attempt to create a registry on a remote host
62 */
63 public RmiObject(final String host, final int port, final String bindingKey) throws RemoteException, AlreadyBoundException
64 {
65 register(host, port, bindingKey);
66 }
67
68 /**
69 * Register this object in the RMI registry. When the RMI registry does not exist yet, it will be created, but <b>only</b>
70 * on the local host. Remote creation of a registry on another computer is not possible. Any attempt to do so will cause an
71 * AccessException to be fired.
72 * @param host String; the host where the RMI registry resides or will be created. Creation is only possible on localhost.
73 * @param port int; the port where the RMI registry can be found or will be created
74 * @param bindingKey String; the key under which this object will be bound in the RMI registry
75 * @throws RemoteException when there is a problem with the RMI registry
76 * @throws AlreadyBoundException when there is already another object bound to the bindingKey
77 * @throws AccessException when there is an attempt to create a registry on a remote host
78 */
79 protected void register(final String host, final int port, final String bindingKey)
80 throws RemoteException, AlreadyBoundException
81 {
82 Throw.whenNull(bindingKey, "bindingKey cannot be null");
83 this.registry = RmiRegistry.getRegistry(host, port);
84 RmiRegistry.bind(this.registry, bindingKey, this);
85 }
86
87 /**
88 * Returns the registry in which this object has been bound, e.g., to look up other objects in the registry.
89 * @return Registry; the registry in which this object has been bound
90 * @throws RemoteException on network error
91 */
92 public Registry getRegistry() throws RemoteException
93 {
94 return this.registry;
95 }
96
97 }