orbd.1 revision 6073:cea72c2bf071
1." Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved. 2." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3." 4." This code is free software; you can redistribute it and/or modify it 5." under the terms of the GNU General Public License version 2 only, as 6." published by the Free Software Foundation. 7." 8." This code is distributed in the hope that it will be useful, but WITHOUT 9." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 10." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 11." version 2 for more details (a copy is included in the LICENSE file that 12." accompanied this code). 13." 14." You should have received a copy of the GNU General Public License version 15." 2 along with this work; if not, write to the Free Software Foundation, 16." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 17." 18." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 19." or visit www.oracle.com if you need additional information or have any 20." questions. 21." 22.TH orbd 1 "10 May 2011" 23 24.LP 25.SH "Name" 26orbd \- The Object Request Broker Daemon 27.LP 28.LP 29\f3orbd\fP is used to enable clients to transparently locate and invoke persistent objects on servers in the CORBA environment. 30.LP 31.LP 32\f3See also:\fP 33.na 34\f2Naming Service\fP @ 35.fi 36http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlNaming.html 37.LP 38.SH "SYNOPSIS" 39.LP 40.nf 41\f3 42.fl 43orbd <\fP\f3options\fP\f3> 44.fl 45\fP 46.fi 47 48.LP 49.SH "DESCRIPTION" 50.LP 51.LP 52The Server Manager included with the \f3orbd\fP tool is used to enable clients to transparently locate and invoke persistent objects on servers in the CORBA environment. The persistent servers, while publishing the persistent object references in the Naming Service, include the port number of the ORBD in the object reference instead of the port number of the Server. The inclusion of an ORBD port number in the object reference for persistent object references has the following advantages: 53.LP 54.RS 3 55.TP 2 56o 57The object reference in the Naming Service remains independent of the server life cycle. For example, the object reference could be published by the server in the Naming Service when it is first installed, and then, independent of how many times the server is started or shutdown, the ORBD will always return the correct object reference to the invoking client. 58.TP 2 59o 60The client needs to lookup the object reference in the Naming Service only once, and can keep re\-using this reference independent of the changes introduced due to server life cycle. 61.RE 62 63.LP 64.LP 65To access ORBD's Server Manager, the server must be started using servertool(1), which is a command\-line interface for application programmers to register, unregister, startup, and shutdown a persistent server. For more information on the Server Manager, see the section in this document titled \f2Server Manager\fP. 66.LP 67.LP 68When \f2orbd\fP starts up, it also starts a naming service. For more information on the naming service, link to 69.na 70\f2Naming Service\fP @ 71.fi 72http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlNaming.html. 73.LP 74.SH "OPTIONS" 75.LP 76.SS 77Required Options 78.LP 79.RS 3 80.TP 3 81\-ORBInitialPort nameserverport 82Specifies the port on which the name server should be started. Once started, \f2orbd\fP will listen for incoming requests on this port. Note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. (required) 83.RE 84 85.LP 86.LP 87 88.LP 89.SS 90OTHER OPTIONS 91.LP 92.RS 3 93.TP 3 94\-port port 95Specifies the activation port where ORBD should be started, and where ORBD will be accepting requests for persistent objects. The default value for this port is 1049. This port number is added to the port field of the persistent Interoperable Object References (IOR). (optional) 96.RE 97 98.LP 99.RS 3 100.TP 3 101\-defaultdb directory 102Specifies the base where the ORBD persistent storage directory \f2orb.db\fP is created. If this option is not specified, the default value is "./orb.db". (optional) 103.RE 104 105.LP 106.RS 3 107.TP 3 108\-serverPollingTime milliseconds 109Specifies how often ORBD checks for the health of persistent servers registered via \f2servertool\fP. The default value is 1,000 ms. The value specified for \f2milliseconds\fP must be a valid positive integer. (optional) 110.RE 111 112.LP 113.RS 3 114.TP 3 115\-serverStartupDelay milliseconds 116Specifies how long ORBD waits before sending a location forward exception after a persistent server that is registered via \f2servertool\fP is restarted. The default value is 1,000 ms. The value specified for \f2milliseconds\fP must be a valid positive integer. (optional) 117.RE 118 119.LP 120.RS 3 121.TP 3 122\-Joption 123Pass \f2option\fP to the Java virtual machine, where \f2option\fP is one of the options described on the reference page for java(1). For example, \f3\-J\-Xms48m\fP sets the startup memory to 48 megabytes. It is a common convention for \f3\-J\fP to pass options to the underlying virtual machine. 124.TP 3 125 126.RE 127 128.LP 129.SH "Starting and Stopping the Naming Service" 130.LP 131.LP 132A Naming Service is a CORBA service that allows 133.na 134\f2CORBA objects\fP @ 135.fi 136http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlGlossary.html#CORBA%20object to be named by means of binding a name to an object reference. The 137.na 138\f2name binding\fP @ 139.fi 140http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlGlossary.html#name%20binding may be stored in the naming service, and a client may supply the name to obtain the desired object reference. 141.LP 142.LP 143Prior to running a client or a server, you will start ORBD. ORBD includes a persistent Naming Service and a transient Naming Service, both of which are an implementation of the COS Naming Service. 144.LP 145.LP 146The \f4Persistent\fP\f3 Naming Service\fP provides persistence for naming contexts. This means that this information is persistent across service shutdowns and startups, and is recoverable in the event of a service failure. If ORBD is restarted, the Persistent Naming Service will restore the naming context graph, so that the binding of all clients' and servers' names remains intact (persistent). 147.LP 148.LP 149\ 150.LP 151.LP 152For backward compatibility, \f2tnameserv\fP, a \f4Transient\fP\f3 Naming Service\fP shipped with older versions of the JDK, is also included in this release of J2SE. A transient naming service retains naming contexts as long as it is running. If there is a service interruption, the naming context graph is lost. 153.LP 154.LP 155The \f2\-ORBInitialPort\fP argument is a required command\-line argument for \f2orbd\fP, and is used to set the port number on which the Naming Service will run. The following instructions assume you can use port 1050 for the Java\ IDL Object Request Broker Daemon. When using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. You can substitute a different port if necessary. 156.LP 157.LP 158To start \f2orbd\fP from a UNIX command shell, enter: 159.LP 160.nf 161\f3 162.fl 163 orbd \-ORBInitialPort 1050& 164.fl 165\fP 166.fi 167 168.LP 169.LP 170From an MS\-DOS system prompt (Windows), enter: 171.LP 172.nf 173\f3 174.fl 175 start orbd \-ORBInitialPort 1050 176.fl 177\fP 178.fi 179 180.LP 181.LP 182Now that ORBD is running, you can run your server and client applications. When running the client and server applications, they must be made aware of the port number (and machine name, if applicable) where the Naming Service is running. One way to do this is to add the following code to your application: 183.LP 184.nf 185\f3 186.fl 187 Properties props = new Properties(); 188.fl 189 props.put("org.omg.CORBA.ORBInitialPort", "1050"); 190.fl 191 props.put("org.omg.CORBA.ORBInitialHost", "MyHost"); 192.fl 193 ORB orb = ORB.init(args, props); 194.fl 195\fP 196.fi 197 198.LP 199.LP 200In this example, the Naming Service is running on port 1050 on host "MyHost". Another way is to specify the port number and/or machine name when running the server or client application from the command line. For example, you would start your "HelloApplication" with the following command line: 201.LP 202.nf 203\f3 204.fl 205 java HelloApplication \-ORBInitialPort 1050 \-ORBInitialHost MyHost 206.fl 207\fP 208.fi 209 210.LP 211.LP 212To stop the naming service, use the relevant operating system command, such as \f2pkill orbd\fP on Solaris, or \f2Ctrl+C\fP in the DOS window in which \f2orbd\fP is running. Note that names registered with the naming service may disappear when the service is terminated if the naming service is transient. The Java IDL naming service will run until it is explicitly stopped. 213.LP 214.LP 215For more information on the Naming Service included with ORBD, see 216.na 217\f2Naming Service\fP @ 218.fi 219http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlNaming.html. 220.LP 221.SH "Server Manager" 222.LP 223.LP 224To access ORBD's Server Manager and run a persistent server, the server must be started using servertool(1), which is a command\-line interface for application programmers to register, unregister, startup, and shutdown a persistent server. When a server is started using \f2servertool\fP, it must be started on the same host and port on which \f2orbd\fP is executing. If the server is run on a different port, the information stored in the database for local contexts will be invalid and the service will not work properly. 225.LP 226.SS 227Server Manager: an Example 228.LP 229.LP 230Using the 231.na 232\f2sample tutorial\fP @ 233.fi 234http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlExample.html for our demonstration, you would run the \f2idlj\fP compiler and \f2javac\fP compiler as shown in the tutorial. To run the Server Manager, follow these steps for running the application: 235.LP 236.LP 237Start \f2orbd\fP. 238.LP 239.LP 240To start \f2orbd\fP from a UNIX command shell, enter: 241.LP 242.LP 243\ 244.LP 245.nf 246\f3 247.fl 248 orbd \-ORBInitialPort 1050 249.fl 250\fP 251.fi 252 253.LP 254.LP 255From an MS\-DOS system prompt (Windows), enter: 256.LP 257.nf 258\f3 259.fl 260 start orbd \-ORBInitialPort 1050 261.fl 262\fP 263.fi 264 265.LP 266.LP 267Note that \f21050\fP is the port on which you want the name server to run. \f2\-ORBInitialPort\fP is a required command\-line argument. When using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. 268.LP 269.LP 270Start the \f2servertool\fP: 271.LP 272.LP 273To start the Hello server, enter: 274.LP 275.nf 276\f3 277.fl 278 servertool \-ORBInitialPort 1050 279.fl 280\fP 281.fi 282 283.LP 284.LP 285Make sure the name server (\f2orbd\fP) port is the same as in the previous step, for example, \f2\-ORBInitialPort 1050\fP. The \f2servertool\fP must be started on the same port as the name server. 286.LP 287.LP 288The \f2servertool\fP command line interface appears. 289.LP 290.LP 291 292.LP 293.LP 294Start the Hello server from the \f2servertool\fP prompt: 295.LP 296.nf 297\f3 298.fl 299 servertool > register \-server HelloServer \-classpath . \-applicationName 300.fl 301 HelloServerApName 302.fl 303\fP 304.fi 305 306.LP 307.LP 308The \f2servertool\fP registers the server, assigns it the name of "HelloServerApName", and displays its server id, along with a listing of all registered servers. 309.LP 310.LP 311 312.LP 313.LP 314Run the client application from another terminal window or prompt: 315.LP 316.LP 317\ 318.LP 319.nf 320\f3 321.fl 322 java HelloClient \-ORBInitialPort 1050 \-ORBInitialHost localhost 323.fl 324\fP 325.fi 326 327.LP 328.LP 329For this example, you can omit \f2\-ORBInitialHost localhost\fP since the name server is running on the same host as the Hello client. If the name server is running on a different host, use \f2\-ORBInitialHost\fP \f2nameserverhost\fP to specify the host on which the IDL name server is running. 330.LP 331.LP 332Specify the name server (\f2orbd\fP) port as done in the previous step, for example, \f2\-ORBInitialPort 1050\fP. 333.LP 334.LP 335\ 336.LP 337.LP 338\ 339.LP 340.LP 341When you have finished experimenting with the Server Manager, be sure to shut down or kill the name server (\f2orbd\fP) and \f2servertool\fP. 342.LP 343.LP 344To shut down \f2orbd\fP from a DOS prompt, select the window that is running the server and enter \f2Ctrl+C\fP to shut it down. To shut down \f2orbd\fPfrom a Unix shell, find the process, and kill it. The server will continue to wait for invocations until it is explicitly stopped. 345.LP 346.LP 347To shut down the \f2servertool\fP, type \f2quit\fP and press the \f2Enter\fP key on the keyboard. 348.LP 349.SH "See Also" 350.LP 351.RS 3 352.TP 2 353o 354.na 355\f2Naming Service\fP @ 356.fi 357http://download.oracle.com/javase/7/docs/technotes/guides/idl/jidlNaming.html 358.br 359.TP 2 360o 361servertool(1) 362.RE 363 364.LP 365.br 366 367.LP 368 369