annotate src/linux/doc/man/orbd.1 @ 13469:8a709c82d16c

Added tag jdk-9+102 for changeset 6eb3c8132e48
author lana
date Thu, 21 Jan 2016 09:46:03 -0800
parents 66c98bd811f1
rev   line source
rgallard@8813 1 '\" t
mfang@12442 2 .\" Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
mfang@12442 4 .\"
mfang@12442 5 .\" This code is free software; you can redistribute it and/or modify it
mfang@12442 6 .\" under the terms of the GNU General Public License version 2 only, as
mfang@12442 7 .\" published by the Free Software Foundation.
mfang@12442 8 .\"
mfang@12442 9 .\" This code is distributed in the hope that it will be useful, but WITHOUT
mfang@12442 10 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
mfang@12442 11 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
mfang@12442 12 .\" version 2 for more details (a copy is included in the LICENSE file that
mfang@12442 13 .\" accompanied this code).
mfang@12442 14 .\"
mfang@12442 15 .\" You should have received a copy of the GNU General Public License version
mfang@12442 16 .\" 2 along with this work; if not, write to the Free Software Foundation,
mfang@12442 17 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
mfang@12442 18 .\"
mfang@12442 19 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
mfang@12442 20 .\" or visit if you need additional information or have any
mfang@12442 21 .\" questions.
mfang@12442 22 .\"
rgallard@8813 23 .\" Arch: generic
rgallard@8813 24 .\" Software: JDK 8
rgallard@8813 25 .\" Date: 21 November 2013
rgallard@8813 26 .\" SectDesc: Java IDL and RMI-IIOP Tools
rgallard@8813 27 .\" Title: orbd.1
rgallard@8813 28 .\"
rgallard@8813 29 .if n .pl 99999
rgallard@8813 30 .TH orbd 1 "21 November 2013" "JDK 8" "Java IDL and RMI-IIOP Tools"
mfang@12442 31 .\" -----------------------------------------------------------------
mfang@12442 32 .\" * Define some portability stuff
mfang@12442 33 .\" -----------------------------------------------------------------
mfang@12442 34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mfang@12442 35 .\"
mfang@12442 36 .\"
mfang@12442 37 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mfang@12442 38 .ie \n(.g .ds Aq \(aq
mfang@12442 39 .el .ds Aq '
mfang@12442 40 .\" -----------------------------------------------------------------
mfang@12442 41 .\" * set default formatting
mfang@12442 42 .\" -----------------------------------------------------------------
mfang@12442 43 .\" disable hyphenation
mfang@12442 44 .nh
mfang@12442 45 .\" disable justification (adjust text to left margin only)
mfang@12442 46 .ad l
mfang@12442 47 .\" -----------------------------------------------------------------
mfang@12442 48 .\" * MAIN CONTENT STARTS HERE *
mfang@12442 49 .\" -----------------------------------------------------------------
duke@0 50
rgallard@8813 51 .SH NAME
rgallard@8813 52 orbd \- Enables clients to locate and call persistent objects on servers in the CORBA environment\&.
rgallard@8813 53 .SH SYNOPSIS
rgallard@8813 54 .sp
rgallard@8813 55 .nf
duke@0 56
rgallard@8813 57 \fBorbd\fR [ \fIoptions\fR ]
rgallard@8813 58 .fi
rgallard@8813 59 .sp
rgallard@8813 60 .TP
rgallard@8813 61 \fIoptions\fR
rgallard@8813 62 Command-line options\&. See Options\&.
rgallard@8813 63 .SH DESCRIPTION
rgallard@8813 64 The \f3orbd\fR command enables clients to transparently locate and call persistent objects on servers in the CORBA environment\&. The Server Manager included with the orbd tool is used to enable clients to transparently locate and call 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:
rgallard@8813 65 .TP 0.2i
rgallard@8813 66 \(bu
rgallard@8813 67 The 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 shut down, the ORBD returns the correct object reference to the calling client\&.
rgallard@8813 68 .TP 0.2i
rgallard@8813 69 \(bu
rgallard@8813 70 The client needs to look up the object reference in the naming service only once, and can keep reusing this reference independent of the changes introduced due to server life cycle\&.
rgallard@8813 71 .PP
rgallard@8813 72 To access the ORBD Server Manager, the server must be started using \f3servertool\fR, which is a command-line interface for application programmers to register, unregister, start up, and shut down a persistent server\&. For more information on the Server Manager, see Server Manager\&.
rgallard@8813 73 .PP
rgallard@8813 74 When \f3orbd\fR starts, it also starts a naming service\&. For more information about the naming service\&. See Start and Stop the Naming Service\&.
rgallard@8813 75 .SH OPTIONS
rgallard@8813 76 .TP
rgallard@8813 77 -ORBInitialPort \fInameserverport\fR
duke@0 78 .br
rgallard@8813 79 Required\&. Specifies the port on which the name server should be started\&. After it is started, \f3orbd\fR listens for incoming requests on this port\&. On Oracle Solaris software, you must become the root user to start a process on a port below 1024\&. For this reason, Oracle recommends that you use a port number above or equal to 1024\&.
rgallard@8813 80 .SS NONREQUIRED\ OPTIONS
rgallard@8813 81 .TP
rgallard@8813 82 -port \fIport\fR
duke@0 83 .br
rgallard@8813 84 Specifies 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)\&.
rgallard@8813 85 .TP
rgallard@8813 86 -defaultdb \fIdirectory\fR
rgallard@8813 87 .br
rgallard@8813 88 Specifies the base where the ORBD persistent storage directory, \f3orb\&.db\fR, is created\&. If this option is not specified, then the default value is \f3\&./orb\&.db\fR\&.
rgallard@8813 89 .TP
rgallard@8813 90 -serverPollingTime \fImilliseconds\fR
rgallard@8813 91 .br
rgallard@8813 92 Specifies how often ORBD checks for the health of persistent servers registered through \f3servertool\fR\&. The default value is 1000 ms\&. The value specified for \f3milliseconds\fR must be a valid positive integer\&.
rgallard@8813 93 .TP
rgallard@8813 94 -serverStartupDelay milliseconds
rgallard@8813 95 .br
rgallard@8813 96 Specifies how long ORBD waits before sending a location forward exception after a persistent server that is registered through \f3servertool\fR is restarted\&. The default value is 1000 ms\&. The value specified for \f3milliseconds\fR must be a valid positive integer\&.
rgallard@8813 97 .TP
rgallard@8813 98 -J\fIoption\fR
rgallard@8813 99 .br
rgallard@8813 100 Passes \f3option\fR to the Java Virtual Machine, where \f3option\fR is one of the options described on the reference page for the Java application launcher\&. For example, \f3-J-Xms48m\fR sets the startup memory to 48 MB\&. See java(1)\&.
rgallard@8813 101 .SS START\ AND\ STOP\ THE\ NAMING\ SERVICE
rgallard@8813 102 A naming service is a CORBA service that allows CORBA objects to be named by means of binding a name to an object reference\&. The name binding can be stored in the naming service, and a client can supply the name to obtain the desired object reference\&.
rgallard@8813 103 .PP
rgallard@8813 104 Before 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\&.
rgallard@8813 105 .PP
rgallard@8813 106 The Persistent Naming Service 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, then the Persistent Naming Service restores the naming context graph, so that the binding of all clients\&' and servers\&' names remains intact (persistent)\&.
rgallard@8813 107 .PP
rgallard@8813 108 For backward compatibility, \f3tnameserv\fR, a Transient Naming Service that shipped with earlier releases of the JDK, is also included in this release of Java SE\&. A transient naming service retains naming contexts as long as it is running\&. If there is a service interruption, then the naming context graph is lost\&.
rgallard@8813 109 .PP
rgallard@8813 110 The \f3-ORBInitialPort\fR argument is a required command-line argument for \f3orbd\fR, and is used to set the port number on which the naming service runs\&. The following instructions assume you can use port 1050 for the Java IDL Object Request Broker Daemon\&. When using Oracle Solaris software, you must become a root user to start a process on a port lower than 1024\&. For this reason, it is recommended that you use a port number above or equal to 1024\&. You can substitute a different port when necessary\&.
rgallard@8813 111 .PP
rgallard@8813 112 To start \f3orbd\fR from a UNIX command shell, enter:
rgallard@8813 113 .sp
rgallard@8813 114 .nf
rgallard@8813 115 \f3orbd \-ORBInitialPort 1050&\fP
rgallard@8813 116 .fi
rgallard@8813 117 .nf
rgallard@8813 118 \f3\fP
rgallard@8813 119 .fi
rgallard@8813 120 .sp
rgallard@8813 121 From an MS-DOS system prompt (Windows), enter:
rgallard@8813 122 .sp
rgallard@8813 123 .nf
rgallard@8813 124 \f3start orbd \-ORBInitialPort 1050\fP
rgallard@8813 125 .fi
rgallard@8813 126 .nf
rgallard@8813 127 \f3\fP
rgallard@8813 128 .fi
rgallard@8813 129 .sp
rgallard@8813 130 Now 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, when applicable) where the Naming Service is running\&. One way to do this is to add the following code to your application:
rgallard@8813 131 .sp
rgallard@8813 132 .nf
rgallard@8813 133 \f3Properties props = new Properties();\fP
rgallard@8813 134 .fi
rgallard@8813 135 .nf
rgallard@8813 136 \f3props\&.put("org\&.omg\&.CORBA\&.ORBInitialPort", "1050");\fP
rgallard@8813 137 .fi
rgallard@8813 138 .nf
rgallard@8813 139 \f3props\&.put("org\&.omg\&.CORBA\&.ORBInitialHost", "MyHost");\fP
rgallard@8813 140 .fi
rgallard@8813 141 .nf
rgallard@8813 142 \f3ORB orb = ORB\&.init(args, props);\fP
rgallard@8813 143 .fi
rgallard@8813 144 .nf
rgallard@8813 145 \f3\fP
rgallard@8813 146 .fi
rgallard@8813 147 .sp
rgallard@8813 148 In this example, the naming service is running on port 1050 on host \f3MyHost\fR\&. 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 \f3HelloApplication\fR with the following command line:
rgallard@8813 149 .sp
rgallard@8813 150 .nf
rgallard@8813 151 \f3java HelloApplication \-ORBInitialPort 1050 \-ORBInitialHost MyHost\fP
rgallard@8813 152 .fi
rgallard@8813 153 .nf
rgallard@8813 154 \f3\fP
rgallard@8813 155 .fi
rgallard@8813 156 .sp
rgallard@8813 157 To stop the naming service, use the relevant operating system command, such as \f3pkill\fR\f3orbd\fR on Oracle Solaris, or \fICtrl+C\fR in the DOS window in which \f3orbd\fR is running\&. Note that names registered with the naming service can disappear when the service is terminated because of a transient naming service\&. The Java IDL naming service will run until it is explicitly stopped\&.
rgallard@8813 158 .PP
rgallard@8813 159 For more information about the naming service included with ORBD, see Naming Service at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/idl/jidlNaming\&.html
rgallard@8813 160 .SH SERVER\ MANAGER
rgallard@8813 161 To access the ORBD Server Manager and run a persistent server, the server must be started with \f3servertool\fR, which is a command-line interface for application programmers to register, unregister, start up, and shut down a persistent server\&. When a server is started using \f3servertool\fR, it must be started on the same host and port on which \f3orbd\fR is executing\&. If the server is run on a different port, then the information stored in the database for local contexts will be invalid and the service will not work properly\&.
rgallard@8813 162 .PP
rgallard@8813 163 See Java IDL: The "Hello World" Example at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/idl/jidlExample\&.html
rgallard@8813 164 .PP
rgallard@8813 165 In this example, you run the \f3idlj\fR compiler and \f3javac\fR compiler as shown in the tutorial\&. To run the ORBD Server Manager, follow these steps for running the application:
rgallard@8813 166 .PP
rgallard@8813 167 Start \f3orbd\fR\&.
rgallard@8813 168 .PP
rgallard@8813 169 UNIX command shell, enter: \f3orbd -ORBInitialPort 1050\fR\&.
rgallard@8813 170 .PP
rgallard@8813 171 MS-DOS system prompt (Windows), enter: \f3s\fR\f3tart orbd -ORBInitialPort 105\fR\f30\fR\&.
rgallard@8813 172 .PP
rgallard@8813 173 Port 1050 is the port on which you want the name server to run\&. The \f3-ORBInitialPort\fR option is a required command-line argument\&. When using Oracle Solaris software, you must become a root user to start a process on a port below 1024\&. For this reason, it is recommended that you use a port number above or equal to 1024\&.
rgallard@8813 174 .PP
rgallard@8813 175 Start the \f3servertool\fR: \f3servertool -ORBInitialPort 1050\fR\&.
rgallard@8813 176 .PP
rgallard@8813 177 Make sure the name server (\f3orbd\fR) port is the same as in the previous step, for example, \f3-ORBInitialPort 1050\&.\fR The \f3servertool\fR must be started on the same port as the name server\&.
rgallard@8813 178 .PP
rgallard@8813 179 In the \f3servertool\fR command line interface, start the \f3Hello\fR server from the \f3servertool\fR prompt:
rgallard@8813 180 .sp
rgallard@8813 181 .nf
rgallard@8813 182 \f3servertool > register \-server HelloServer \-classpath \&. \-applicationName\fP
rgallard@8813 183 .fi
rgallard@8813 184 .nf
rgallard@8813 185 \f3 HelloServerApName\fP
rgallard@8813 186 .fi
rgallard@8813 187 .nf
rgallard@8813 188 \f3\fP
rgallard@8813 189 .fi
rgallard@8813 190 .sp
rgallard@8813 191 The \f3servertool\fR registers the server, assigns it the name \f3HelloServerApName\fR, and displays its server ID with a listing of all registered servers\&.Run the client application from another terminal window or prompt:
rgallard@8813 192 .sp
rgallard@8813 193 .nf
rgallard@8813 194 \f3java HelloClient \-ORBInitialPort 1050 \-ORBInitialHost localhost\fP
rgallard@8813 195 .fi
rgallard@8813 196 .nf
rgallard@8813 197 \f3\fP
rgallard@8813 198 .fi
rgallard@8813 199 .sp
rgallard@8813 200 For this example, you can omit \f3-ORBInitialHost localhost\fR because the name server is running on the same host as the \f3Hello\fR client\&. If the name server is running on a different host, then use the -\f3ORBInitialHost nameserverhost\fR option to specify the host on which the IDL name server is running\&.Specify the name server (\f3orbd\fR) port as done in the previous step, for example, \f3-ORBInitialPort 1050\fR\&. When you finish experimenting with the ORBD Server Manager, be sure to shut down or terminate the name server (\f3orbd\fR) and \f3servertool\fR\&. To shut down \f3orbd\fR from am MS-DOS prompt, select the window that is running the server and enter \fICtrl+C\fR to shut it down\&.
rgallard@8813 201 .PP
rgallard@8813 202 To shut down \f3orbd\fR from an Oracle Solaris shell, find the process, and terminate with the \f3kill\fR command\&. The server continues to wait for invocations until it is explicitly stopped\&. To shut down the \f3servertool\fR, type \fIquit\fR and press the \fIEnter\fR key\&.
rgallard@8813 203 .SH SEE\ ALSO
rgallard@8813 204 .TP 0.2i
rgallard@8813 205 \(bu
rgallard@8813 206 servertool(1)
rgallard@8813 207 .TP 0.2i
rgallard@8813 208 \(bu
rgallard@8813 209 Naming Service at http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/idl/jidlNaming\&.html
mfang@12442 210 .RE
mfang@12442 211 .br
mfang@12442 212 'pl 8.5i
mfang@12442 213 'bp