diff options
author | doccvs <doccvs@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2001-04-01 22:03:52 +0000 |
---|---|---|
committer | doccvs <doccvs@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2001-04-01 22:03:52 +0000 |
commit | ba9d92b8cc0162185500f0736ce1e324837d1441 (patch) | |
tree | d96dfbfbf2bb0cc47cb9a34b4c3f00cbc809573e /TAO/docs | |
parent | 896f3a0be926f77ef823127d4456d1eaa5f5e8da (diff) | |
download | ATCD-ba9d92b8cc0162185500f0736ce1e324837d1441.tar.gz |
Thanks to John Ashmun <John.ASHMUN@esca.com> for this proof-read
page.
Diffstat (limited to 'TAO/docs')
6 files changed, 237 insertions, 237 deletions
diff --git a/TAO/docs/tutorials/Quoter/RT_Event_Service/index.html b/TAO/docs/tutorials/Quoter/RT_Event_Service/index.html index 22b8d382917..a76321a7946 100644 --- a/TAO/docs/tutorials/Quoter/RT_Event_Service/index.html +++ b/TAO/docs/tutorials/Quoter/RT_Event_Service/index.html @@ -16,19 +16,19 @@ <A HREF="../Event_Service/index.html"> TAO's COS Event Service </A> - to receive updated stock prices. - But what if we are not interested in all the stocks? + to receive updated stock prices, + but what if we are not interested in all the stocks? One approach is to use multiple event channels, each one - carrying different traffic, - for example, + carrying different traffic. + For example, each event channel could carry only a subset of the stocks. In this section we will explore another solution, using TAO's real-time Event Service to perform filtering for us. TAO's real-time Event Service can do many other things, like preserving priority end-to-end, - using multicast to conserver network resources, - generate timeout and interval events - and it can collaborate with the TAO's Scheduling Service to + using multicast to conserve network resources, + generating timeout and interval events, + and it can collaborate with TAO's Scheduling Service to analyze the schedulability of your system. </P> @@ -36,20 +36,20 @@ <P>For this example we will use the same data structures that we used in the previous example, - i.e. the events will be identical. + i.e., the events will be identical. TAO's RT Event Service can be configured to carry your events in a type-safe manner, or you can use custom marshaling to send non-IDL structures in the event, - but it is easier to use it as the COS Event Service first. + but it is easier to use it like the COS Event Service first. </P> <H3>Connecting as a consumer</H3> - <P>Connecting as a consumer is very similar, some of the base + <P>Connecting as a consumer is very similar. Some of the base classes and signatures change, but it is basically the same idea: - First let us defined the consumer object: + First let us define the consumer object: </P> <PRE> class Stock_Consumer : public POA_RtecEventComm::PushConsumer { @@ -62,8 +62,8 @@ public: // details omitted }; </PRE> - <P>Notice that we receive an event set instead of a single event, - the event channel can use this feature to queue multiple events + <P>Notice that we receive an event set instead of a single event. + The event channel can use this feature to queue multiple events and push them in a single operation. First we need to extract the event data from the any: </P> @@ -82,7 +82,7 @@ Stock_Consumer::push (const RtecEventComm::EventSet &data, <P>Notice that the events have more structure, they have a clearly separated header and data, and the data has more than just an any. - The header is used to provide filtering, + The header is used to provide filtering, and the event data field can be configured at compile time to carry whatever IDL structures you want. Now we can print out the new stock price: @@ -104,7 +104,7 @@ Stock_Consumer::disconnect_push_consumer (CORBA::Environment &) this->supplier_proxy_ = CosEventChannelAdmin::ProxyPushSupplier::_nil (); } </PRE> - <P>As with the COS Event Channel we can voluntarily disconnect + <P>As with the COS Event Channel we can voluntarily disconnect, too: </P> <PRE> @@ -147,8 +147,8 @@ Stock_Consumer::connect (RtecEventChannelAdmin::ConsumerAdmin_ptr consumer_admin this->supplier_proxy_ = consumer_admin->obtain_push_supplier (); </PRE> - <P>Now we list the events that we want to receive, - we use a simple algorithm to assign an event type to each stock + <P>Now we list the events that we want to receive. + We use a simple algorithm to assign an event type to each stock symbol: </P> <PRE> @@ -211,9 +211,9 @@ Quoter_Stock_i::set_price (CORBA::Double new_price) { this->data_.price = new_price; </PRE> - <P>Next we prepare the event, - this time we must create a sequence, but we just have one - element on it: + <P>Next we prepare the event. + This time we must create a sequence, but we just have one + element in it: </P> <PRE> RtecEventComm::EventSet event (1); @@ -269,7 +269,7 @@ Quoter_Stock_i::set_price (CORBA::Double new_price) this->consumer_proxy_ = supplier_admin->obtain_push_consumer (); </PRE> - <P>We build our publications, so the event channel can match + <P>We build our publications so the event channel can match consumers and suppliers based on their common events: </P> <PRE> @@ -283,7 +283,7 @@ Quoter_Stock_i::set_price (CORBA::Double new_price) ACE_SupplierQOS_Factory publications; publications.insert_type (type, source, 0, 1); </PRE> - <P>finally we connect to the consumer proxy: + <P>Finally we connect to the consumer proxy: </P> <PRE> RtecEventComm::PushSupplier_var supplier = @@ -314,7 +314,7 @@ Quoter_Stock_i::disconnect_push_supplier (CORBA::Environment &) along with a sample <A HREF="client.cpp">client.cpp</A>. And other support files - <A HREF="Quoter.idl">Quoter.idl</A>, + <A HREF="../Event_Service/Quoter.idl">Quoter.idl</A>, <A HREF="Makefile">Makefile</A>, <A HREF="Stock_i.h">Stock_i.h</A>, <A HREF="Stock_i.cpp">Stock_i.cpp</A>, @@ -336,10 +336,10 @@ Quoter_Stock_i::disconnect_push_supplier (CORBA::Environment &) <PRE> $ $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service </PRE> - <P>TAO's RT Event Service + <P>The CORBA Event Service </P> <PRE> -$ $TAO_ROOT/orbsvcs/Event_Service/Event_Service +$ $TAO_ROOT/orbsvcs/Event_Service/Event_Service -ORBSvcConf ec.conf </PRE> <P>Now you can run your client: @@ -352,7 +352,7 @@ $ client AAAA CCCC $ server MSFT BBBB CCCC < stock_list.txt </PRE> <P>Here is the - <A HREF="../Event_Service/stock_list.txt">stock_list.txt file</A>. + <A HREF="stock_list.txt">stock_list.txt file</A>. </P> <H3>Exercise 2</H3> @@ -369,9 +369,9 @@ $ server QQQQ < stock_list2.txt <P>Do the clients receive all the events from both servers? </P> <P>Here are the - <A HREF="../Event_Service/stock_list.txt">stock_list1.txt</A> + <A HREF="stock_list1.txt">stock_list1.txt</A> and - <A HREF="../Event_Service/stock_list.txt">stock_list2.txt</A> + <A HREF="stock_list2.txt">stock_list2.txt</A> files. </P> @@ -379,7 +379,7 @@ $ server QQQQ < stock_list2.txt <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> <!-- Created: Sat Nov 27 15:47:01 CST 1999 --> <!-- hhmts start --> -Last modified: Thu Mar 15 14:18:34 PST 2001 +Last modified: Sun Apr 1 14:17:17 PDT 2001 <!-- hhmts end --> </body> </html> diff --git a/TAO/docs/tutorials/Quoter/Simple/Client/index.html b/TAO/docs/tutorials/Quoter/Simple/Client/index.html index 9ea2fee56b1..199e556546a 100644 --- a/TAO/docs/tutorials/Quoter/Simple/Client/index.html +++ b/TAO/docs/tutorials/Quoter/Simple/Client/index.html @@ -12,12 +12,12 @@ <h3>Introduction - A very simple client</h3> - <P>We will start with a reasonably simple IDL interface, we want + <P>We will start with a reasonably simple IDL interface: we want to build a stock quoter server, some interface to query the - prices of stock. To make a life interesting we will use a - different CORBA object for each Stock, this may sound as an + prices of stock. To make life interesting we will use a + different CORBA object for each stock. This may sound like overkill, but it will motivate a number of elements that are - interesting to learn on the start. + interesting to learn at the start. </P> <H3>Defining the IDL interfaces</H3> @@ -42,20 +42,20 @@ }; </PRE> <P>We also need some interface to gain access to the - <CODE>Stock</CODE> object references from their symbols, - usually we call this kind of interface a <EM>Factory</EM>, - and they look like this: + <CODE>Stock</CODE> object references from their symbols. + Usually we call this kind of interface a <EM>Factory</EM>, + and it looks like this: </P> <PRE> interface Stock_Factory { Stock get_stock (in string stock_symbol); }; </PRE> - <P>Notice how arguments have a <EM>direction</EM>, they are + <P>Notice how arguments have a <EM>direction</EM>: they are qualified as <EM>input only (<CODE>in</CODE>)</EM>, - <EM>output only (<CODE>out</CODE>)</EM> + <EM>output only (<CODE>out</CODE>)</EM>, or <EM>input-output (<CODE>inout</CODE>)</EM> arguments. - There is a problem though, what happens if the stock symbol is + There is a problem, though: what happens if the stock symbol is invalid? The CORBA way is to raise an exception: </P> <PRE> @@ -71,15 +71,15 @@ }; </PRE> - <P>Finally we put all this IDL constructs in a module to avoid + <P>Finally we put all these IDL constructs in a module to avoid namespace pollution to obtain the <A HREF="../Quoter.idl">Quoter.idl</A> file. </P> <H3>The Generated Files</H3> - <P>Let's take a minute to look at the generated code, - you don't need to do this often, in fact you rarely have to do + <P>Let's take a minute to look at the generated code. + You don't need to do this often, in fact you rarely have to do it at all. But doing it once is educative and can demystify the role of the IDL compiler. </P> @@ -91,51 +91,51 @@ $ $ACE_ROOT/TAO/TAO_IDL/tao_idl Quoter.idl </PRE> <P>The complete documentation of the IDL compiler and its options - are included in the + are included in <A HREF="../../../../compiler.html">compiler.html</A>. - naturally this file is included in the distribution. + Naturally this file is included in the distribution. </P> - <P>TAO generates 9 files for each IDL file, - the <CODE>QuoterC.h</CODE>, <CODE>QuoterC.i</CODE> - and <CODE>QuoterC.cpp</CODE> contain the client-side interfaces, - notice that the inline functions are on a separate file so you + <P>TAO generates 9 files for each IDL file. + <CODE>QuoterC.h</CODE>, <CODE>QuoterC.i</CODE> + and <CODE>QuoterC.cpp</CODE> contain the client-side interfaces. + Notice that the inline functions are in a separate file so you can optionally compile them out-of-line for smaller code. Pure clients only need to link the object file generated from <CODE>QuoterC.cpp</CODE>. </P> <P> - Similarly the <CODE>QuoterS.h</CODE>, <CODE>QuoterS.i</CODE> + Similarly, <CODE>QuoterS.h</CODE>, <CODE>QuoterS.i</CODE> and <CODE>QuoterS.cpp</CODE> contain the server-side <EM>skeletons</EM>. Servers must link the object files generated from <CODE>QuoterS.cpp</CODE> <STRONG>and</STRONG> <CODE>QuoterC.cpp</CODE>. </P> <P> - Finally <CODE>QuoterS_T.h</CODE>, <CODE>QuoterS_T.i</CODE> - and <CODE>QuoterS_T.cpp</CODE> contain the <EM>TIE</EM> classes, - this are the standard (after the CORBA 2.2 spec) skeletons based + Finally, <CODE>QuoterS_T.h</CODE>, <CODE>QuoterS_T.i</CODE> + and <CODE>QuoterS_T.cpp</CODE> contain the <EM>TIE</EM> classes. + These are the standard (after the CORBA 2.2 spec) skeletons based on composition instead of inheritance. - They are on a separate file only because some compilers cannot + They are in separate files only because some compilers cannot handle mixed template and non-template code in the same source - file, you <STRONG>do not</STRONG> need to compile these files in any + file. You <STRONG>do not</STRONG> need to compile these files on any platform. However, the files are required to compile <CODE>QuoterS.cpp</CODE>. - Also notice that if your platform does not support namespaces + Also notice that if your platform does not support namespaces, then you may be unable to use the TIE approach for some IDL interfaces. </P> <P>All the extensions and suffixes discussed above can be modified - using options in the IDL compiler, check the documentation for - more details. Notice though that you should use consistent + using options of the IDL compiler; check the documentation for + more details. Notice, though, that you should use consistent extensions across your project, otherwise you may have problems with some <CODE>#include</CODE> directives in your IDL source. </P> <H3>Building a simple client</H3> - <P>With our simple IDL interface ready we want to start with a + <P>With our simple IDL interface ready, we want to start with a simple client. The first thing to do in any CORBA client or server is initialize the ORB: </P> @@ -149,7 +149,7 @@ int main (int argc, char* argv[]) "" /* the ORB name, it can be anything! */); </PRE> <P>IDL supports variable-length types whose sizes are not known - at compile time. Hence they must be dynamically allocated at run + at compile time, hence they must be dynamically allocated at run time. <CODE>_var</CODE> types relieve us of the explicit memory management of the variable-length types and thus hide the differences between fixed and variable-length structured types. @@ -157,8 +157,8 @@ int main (int argc, char* argv[]) <P>Since the ORB initialization can fail, and in fact, any CORBA operation can raise a <CODE>CORBA::SystemException</CODE> we use a <CODE>try/catch</CODE> block to check for any failures. - Needless to say this is very naive, some failures can be - temporary and we should have a better way to recover from + Needless to say, this is very naive; some failures can be + temporary, and we should have a better way to recover from errors, but this is enough for our example. In consequence, at the end of <CODE>main()</CODE> we catch all kinds of CORBA exceptions: @@ -172,7 +172,7 @@ int main (int argc, char* argv[]) } </PRE> <P>We must not forget that the ORB is a resource that must be - released by the application, until CORBA 2.3 there was no + released by the application. Until CORBA 2.3 there was no standard way to do this. TAO has adopted the new specification, so our client should really look like this: </P> @@ -196,22 +196,22 @@ int main (int argc, char* argv[]) } </PRE> - <P>Just a few words about the ORB name, the spec requires the ORB + <P>Just a few words about the ORB name: The spec requires the ORB to return the same ORB pointer if the same ORB id is used in - <CODE>CORBA::init</CODE>, + <CODE>CORBA::init</CODE>, and the implementation is free to return the same pointer even if different ids are used. - Usually this is not a problem as most applications instantiate a + Usually this is not a problem, as most applications instantiate a single ORB. TAO is one of the few CORBA implementations that - actually support multiple ORB pointers, this can be important - for real-time applications where each ORB executes at different + actually supports multiple ORB pointers. This can be important + for real-time applications where each ORB executes at a different priority. </P> - <P>Now that we have the ORB pointer we can start bootstrapping the - application, normally we would use the Naming Service, - Trading Service or the Interoperable Naming Service to locate - the stock factory, but for simplicity let us use just an IOR + <P>Now that we have the ORB pointer, we can start bootstrapping the + application. Normally we would use the Naming Service, + Trading Service, or the Interoperable Naming Service to locate + the stock factory, but for simplicity, let us use just an IOR string passed in the first argument. </P> <P>The easiest way is to use the first argument to get the string, @@ -225,13 +225,13 @@ int main (int argc, char* argv[]) Quoter::Stock_Factory_var factory = Quoter::Stock_Factory::_narrow (factory_object.in ()); </PRE> - <P>The <CODE>_narrow()</CODE> tests is used to test if a reference + <P>The <CODE>_narrow()</CODE> is used to test if a reference is of the specified type. If the reference is of the specified - type, it returns a non-nil reference. Else it returns a nil. + type, it returns a non-nil reference, else it returns a nil. </P> - <P>There are a few interesting things about TAO, first it supports + <P>There are a few interesting things about TAO: First, it supports the <CODE>file:</CODE> scheme for object references, so the first - argument could be <CODE>file://a_file_name</CODE>, in that case + argument could be <CODE>file://a_file_name</CODE>. In that case, the ORB will open the file named <CODE>"a_file_name"</CODE> and read the IOR from that file. TAO also supports the <CODE>corbaloc:</CODE> scheme, for example @@ -245,19 +245,19 @@ int main (int argc, char* argv[]) <PRE> #include "QuoterC.h" </PRE> - notice that this is all you need to include, the IDL compiler + Notice that this is all you need to include; the IDL compiler generates code that includes all the required internal header files. - When you use TAO services don't forget to include their - corresponding header file too. + When you use TAO services, don't forget to include their + corresponding header files too. </P> <P>Another interesting TAO feature is the support for - <CODE>_unchecked_narrow()</CODE>, - this is part of the CORBA Messaging specification and + <CODE>_unchecked_narrow()</CODE>. + This is part of the CORBA Messaging specification and essentially performs the same work as <CODE>_narrow()</CODE>, - but it does not check the types remotely, - if you have compile time knowledge that ensures the correctness + but it does not check the types remotely. + If you have compile time knowledge that ensures the correctness of the narrow operation, it is more efficient to use the unchecked version. </P> @@ -275,32 +275,32 @@ int main (int argc, char* argv[]) <H3>Exercise 1</H3> - <P>Complete the client implementation, it should be easy at this - point, but it will give you a chance to setup your environment + <P>Complete the client implementation. It should be easy at this + point, but it will give you a chance to set up your environment and become familiar with the basics of building a TAO application. </P> - <P>You don't need to do everything, - the <A HREF="../Quoter.idl">Quoter.idl</A> file and - a <A HREF="Makefile">Makefile</A> are provided, just + <P>You don't need to do everything. + The <A HREF="../Quoter.idl">Quoter.idl</A> file and + a <A HREF="Makefile">Makefile</A> are provided. Just implement the <CODE>client.cpp</CODE> file. Cut & paste the ORB initialization code, and anything you find - useful from above, you can even cheat and look at the solution, - but it is going to be some really boring 30 minutes if you do! + useful from above (you can even cheat and look at the solution, + but it is going to be some really boring 30 minutes if you do!). </P> <H4>Solution</H4> <P>Look at the - <A HREF="client.cpp">client.cpp</A> file, it should + <A HREF="client.cpp">client.cpp</A> file; it should not be much different from yours. Count the number of lines in - your client, the idl file and the <CODE>QuoterC.*</CODE> files, do - you want to write all that code ever again? + your client, the idl file and the <CODE>QuoterC.*</CODE> files. Do + you want to write all that code over again? </P> <H3>Testing</H3> - <P>To test this application we need a server working, this is a + <P>To test this application we need a server working, a good excuse to go to the next <A HREF="../Server/index.html">lesson</A> in the tutorial. </P> @@ -309,7 +309,7 @@ int main (int argc, char* argv[]) <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> <!-- Created: Sat Nov 27 15:47:01 CST 1999 --> <!-- hhmts start --> -Last modified: Wed Nov 15 16:19:04 PST 2000 +Last modified: Sun Apr 1 14:55:08 PDT 2001 <!-- hhmts end --> </body> </html> diff --git a/TAO/docs/tutorials/Quoter/Simple/Impl-Repo/index.html b/TAO/docs/tutorials/Quoter/Simple/Impl-Repo/index.html index e1243d5cada..e7a3c054c68 100644 --- a/TAO/docs/tutorials/Quoter/Simple/Impl-Repo/index.html +++ b/TAO/docs/tutorials/Quoter/Simple/Impl-Repo/index.html @@ -12,15 +12,15 @@ <h3>Implementation Repository</h3> <P> In the previous example, the client must contact the server - atleast once. If the server has been moved to a different host or - port or if the server is down, binding between the client and + at least once. If the server has been moved to a different host or + port, or if the server is down, binding between the client and the server fails. Indirect binding through an external location broker like the Implementation Repository solves this problem. </P> <P>An implementation repository maintains a data structure known as a server table to keep track of the servers. It maintains a registry of known servers, records which server is currently - running on which host and at which port number and starts + running on which host and at which port number, and starts servers on demand if they are registered to do so. </P> <P> When a server @@ -35,7 +35,7 @@ information of the actual server. The client now sends the request to the actual server. </P> - <P>In this example, lets proceed to modify our previous stock + <P>In this example, let's proceed to modify our previous stock factory example to support indirect binding through an implementation repository. </P> @@ -67,13 +67,13 @@ <H3>Testing</H3> <P>To test your changes, you need to run three programs. The first - step would be to startup the Implementation Repository provided - with TAO. We need to dump the IOR of the ImplRepo_Service to a file + step is to start up the Implementation Repository provided + with TAO. We need to dump the IOR of the ImplRepo_Service to a file, so that we can use it later to use the implementation repository for the initial service. </P> <PRE> - $ $TAO_ROOT/orbsvcs/ImplRepo_Service/ImplRepo_Service -o implrepo.ior -d 0 -ORBobjrefstyle URL & + $ $TAO_ROOT/orbsvcs/ImplRepo_Service -o implrepo.ior -d 0 -ORBobjrefstyle URL & TAO Implementation Repository </PRE> @@ -92,14 +92,14 @@ Successfully registered server <childPOA> </PRE> - <P> We use the <CODE>-ORBInitRef</CODE> option to the IOR in - <CODE>implrepo.ior</CODE> file and the <CODE>-ORBUseIMR</CODE> + <P> We specify the <CODE>-ORBInitRef</CODE> option to use the IOR in + the <CODE>implrepo.ior</CODE> file and the <CODE>-ORBUseIMR</CODE> option to tell the server to use the IMR for notification of its startup and shutdown. </P> - <P>The next step would be to generate a simple IOR for our server + <P>The next step is to generate a simple IOR for our server to be used with the IMR, using the - <CODE>ior</CODE> option and write it to <CODE>stock_factory.ior</CODE>. + <CODE>ior</CODE> option, and write it to <CODE>stock_factory.ior</CODE>. </P> <PRE> @@ -109,7 +109,7 @@ iioploc://1.1@doc.ece.uci.edu:2690/childPOA </PRE> <P> From now, the implementation repository is all set to keep - track of our server and do the needful on a method invocaation + track of our server and do the needful on a method invocation on our server. </P> <P> Now, execute the client as usual. @@ -120,7 +120,7 @@ The price of a stock in "Microsoft, Inc." is $91 The price of a stock in "RedHat, Inc." is $210 </PRE> - <P> For testing the persistency of the POA, lets shutdown the + <P> For testing the persistency of the POA, let's shut down the server and then run the client. </P> <PRE> @@ -136,21 +136,21 @@ </PRE> <H3>More Reading</H3> <P>More information on Implementation Repository is - <A HREF="../../../../implrepo/index.html">here</A>. + <A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/implrepo/index.html">here</A>. </P> <P>The <A HREF="http://www.triodia.com/staff/michi-henning.html">Henning</A> and <A HREF="http://www.iona.com/hyplan/vinoski/">Vinoski</A> <A HREF="http://www.iona.com/hyplan/vinoski/#book">CORBA book</A> discusses POA policies in detail. Likewise, the Schmidt and Vinoski <A HREF="http://www.cs.wustl.edu/~schmidt/report-doc.html">columns</A> in C++ Report also include several articles about the POA. Finally, the <A HREF="http://www.cs.wustl.edu/~schmidt/TAO.html">TAO</A> - distribution includes <A HREF="../../../../../examples/POA">examples</A> that illustrate how + distribution includes <A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/examples/POA">examples</A> that illustrate how to use the POA policies. </P> <hr> <address><a href="mailto:pgontla@ece.uci.edu">Priyanka Gontla</a></address> <!-- Created: Wed Mar 29 17:35:30 PST 2000 --> <!-- hhmts start --> -Last modified: Fri May 12 12:32:03 PDT 2000 +Last modified: Sun Apr 1 14:59:29 PDT 2001 <!-- hhmts end --> </body> </html> diff --git a/TAO/docs/tutorials/Quoter/Simple/ImprovedServer/index.html b/TAO/docs/tutorials/Quoter/Simple/ImprovedServer/index.html index 5c150bc540f..55a005a46a4 100644 --- a/TAO/docs/tutorials/Quoter/Simple/ImprovedServer/index.html +++ b/TAO/docs/tutorials/Quoter/Simple/ImprovedServer/index.html @@ -22,25 +22,25 @@ <P>In our previous example we used two fields of the <CODE>Quoter_Stock_Factory_i</CODE> to represent the stock quotes. If we wish to create hundreds of stock objects this approach - would not scale, we need to use some collection to keep track of + would not scale. We need to use some collection to keep track of the Stock objects, possibly indexed by the stock symbol. One solution is to use an STL map or something similar, but this - is clearly wasteful, after all the ORB is also keeping a + is clearly wasteful. After all, the ORB is also keeping a collection of objects, indexed by the object ids. - If we only could choose the ids ourselves then our problem would - be solved, - the good news is that the POA allows this, + If we only could choose the ids ourselves, then our problem would + be solved. + The good news is that the POA allows this, the bad news is that we must create a child POA for that. Why? Because the Root POA ids are assigned by the ORB, and we - don't want to conflict with those, - furthermore, creating a separate POA is easier to manage, as + don't want to conflict with those. + Furthermore, creating a separate POA is easier to manage, as multiple components of the application can get their own POA, that they can treat as a private namespace. </P> <H3>Child POA creation</H3> - <P>As before we gain access to the RootPOA: + <P>As before, we gain access to the RootPOA: </P> <PRE> CORBA::Object_var poa_object = @@ -48,14 +48,14 @@ PortableServer::POA_var poa = PortableServer::POA::_narrow (poa_object.in ()); </PRE> - <P>Now we create the policies for the child poa, - in this case we want the <CODE>USER_ID</CODE> policy so we can - assign our own ids, - we also want the <CODE>NO_IMPLICIT_ACTIVATION</CODE> policies to + <P>Now we create the policies for the child poa. + In this case we want the <CODE>USER_ID</CODE> policy so we can + assign our own ids. + We also want the <CODE>NO_IMPLICIT_ACTIVATION</CODE> policy, to have more control over additions to our POA. The POA has more policies that we can control, but we will use - the defaults in this example, - there are many examples in <CODE>$TAO_ROOT/examples/POA/</CODE> that + the defaults in this example. + There are many examples in <CODE>$TAO_ROOT/examples/POA/</CODE> that show how to use other policies in the POA. </P> <P>The policies are stored in a sequence, so we first create the @@ -95,8 +95,8 @@ <H3>Activating objects in the child POA</H3> - <P>Now we must use this POA to activate the stock objects, - to keep the example simple we will assume that we read the list + <P>Now we must use this POA to activate the stock objects. + To keep the example simple, we will assume that we read the list of stocks from the stdin, as in: </P> <PRE> @@ -115,7 +115,7 @@ // The interesting stuff goes here! } </PRE> - <P>For each trio of symbol, full name and price we create a stock + <P>For each trio of symbol, full name, and price, we create a stock implementation object: </P> <PRE> @@ -125,7 +125,7 @@ <P>The <CODE>ServantBase_var</CODE> acts like an auto pointer and will take care of deallocation in case there is an exception. This time we cannot use <CODE>_this()</CODE> to activate the servant - though, we want to create our own ids: + though, because we want to create our own ids: </P> <PRE> PortableServer::ObjectId_var oid = @@ -147,7 +147,7 @@ <H3>Modifying the Stock Factory</H3> <P>Now we need to implement a different version of the stock - factory, we pass a reference to the child POA in the constructor + factory. We pass a reference to the child POA into the constructor and keep a reference to it: </P> <PRE> @@ -166,12 +166,12 @@ private: }; </PRE> <P>Notice that we duplicate the POA, following the usual CORBA - memory rules for input arguments, since the constructor is not a - CORBA operations we could use are rules we wised, but it is less + memory rules for input arguments. Since the constructor is not a + CORBA operation, we could use any rules we wished, but it is less confusing if we stick to the CORBA set. </P> <P>The implementation of the <CODE>get_stock</CODE> operation is more - interesting, first we create an object id based on the symbol: + interesting. First we create an object id based on the symbol: </P> <PRE> Quoter::Stock_ptr @@ -181,7 +181,7 @@ Quoter_Stock_Factory_i::get_stock (const char *symbol) PortableServer::ObjectId_var oid = PortableServer::string_to_ObjectId (symbol); </PRE> - <P>next we lookup that object id in the POA: + <P>next we look up that object id in the POA: </P> <PRE> try { @@ -195,7 +195,7 @@ Quoter_Stock_Factory_i::get_stock (const char *symbol) return Quoter::Stock::_narrow (tmp.in ()); } </PRE> - <P>If the symbol was invalid the POA will not find the right + <P>If the symbol was invalid, the POA will not find the right object id and raise an exception: </P> <PRE> @@ -207,25 +207,25 @@ Quoter_Stock_Factory_i::get_stock (const char *symbol) <H3>Memory management for the Stock objects</H3> - <P>So far we have not discussed memory management for servants, - this is a good opportunity to do it because the stock objects + <P>So far we have not discussed memory management for servants. + This is a good opportunity to do it, because the stock objects are completely controlled by the POA. - The POA provides reference counting for the Servants, you are + The POA provides reference counting for the Servants. You are <STRONG>not</STRONG> required to use reference counting, but if - you do most of the memory management is extremely simple. + you do, most of the memory management is extremely simple. So why is reference counting not used all the time? Because some - applications do not require it, for example, + applications do not require it. For example, our previous simple server did not require any complex memory - management as the objects where all created on the stack. + management, as the objects were all created on the stack. </P> - <P>To use the reference counting features in the POA you must + <P>To use the reference counting features in the POA, you must override the <CODE>_add_ref()</CODE> and <CODE>_remove_ref()</CODE> methods, to increase and decrease the reference count. Once the - count reaches 0 you can safely remove the object (but remember + count reaches 0, you can safely remove the object (but remember to start the count at 1!). Implementing these methods in a thread safe way is a tedious - task, to simplify the task we use a mixin with the + task. To simplify the task, we use a mixin with the <CODE>PortableServer::RefCountServantBase</CODE> class, as in: </P> <PRE> @@ -243,13 +243,13 @@ public: <P>TAO's implementation of the <CODE>RefCountServantBase</CODE> is even thread safe, so you can use this technique in your multi-threaded servers to dynamically destroy objects. - You simply delegate control on the POA, - once you deactivate the object the POA will only invoke + You simply delegate control to the POA. + Once you deactivate the object, the POA will only invoke <CODE>_remove_ref()</CODE> once all the threads performing calls on an object terminate, so the object is not removed if it is still in use. Just remember to increment the reference count if you need to - use it too. + use it, too. </P> <H3>Exersice</H3> @@ -269,7 +269,7 @@ public: </LI> <LI> <A HREF="../Server/server.cpp">server.cpp</A>: Create the child POA, - initialize the stock objects from the stdin and create the + initialize the stock objects from the stdin, and create the right stock factory class. </LI> </UL> @@ -297,7 +297,7 @@ public: </UL> </P> - <P>Does this solution scale when the number of stock symbols in in + <P>Does this solution scale when the number of stock symbols is in the thousands or millions? Find out about Servant Locators and Servant Activators in the POA! </P> @@ -306,15 +306,15 @@ public: <P>A sample <A HREF="stock_list.txt">input file</A> - is available, you can use the - <A HREF="../Client/index.html">simpl client</A> to check the + is available. You can use the + <A HREF="../Client/index.html">simple client</A> to check the results, as follows: <PRE> $ server < stock_list.txt > ior_file $ client file://ior_file AAAA BBBB MSFT RHAT CCCC </PRE> - also test invalid symbols! + Also test invalid symbols! </P> <H3>More Reading</H3> @@ -328,7 +328,7 @@ HREF="http://www.triodia.com/staff/michi-henning.html">Henning</A> and in C++ Report also include several articles about the POA. Finally, the <A HREF="http://www.cs.wustl.edu/~schmidt/TAO.html">TAO</a> distribution includes <A -HREF="../../../../../examples/POA">examples</A> +HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/examples/POA">examples</A> that illustrate how to use the POA policies. </P> @@ -336,7 +336,7 @@ that illustrate how to use the POA policies. <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> <!-- Created: Sat Nov 27 15:47:01 CST 1999 --> <!-- hhmts start --> -Last modified: Mon Apr 3 02:28:22 CDT 2000 +Last modified: Sun Apr 1 15:01:21 PDT 2001 <!-- hhmts end --> </body> </html> diff --git a/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html b/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html index 04451cddc4c..0eb83e9e6d7 100644 --- a/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html +++ b/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html @@ -23,37 +23,37 @@ to create an object with a persistent object reference. </P> <P> - The characteristics of a POA are controlled via POA policies, + The characteristics of a POA are controlled via POA policies that are specified when the POA is created. - POA policies are have the same form: their values are specified + POA policies all have the same form: their values are specified at creation time using an enumerated type. In our example we will use the <CODE>LifeSpanPolicy</CODE> that controls how the lifetime of object references relates to - the lifetime of the POAs that generate the object reference - and the <CODE>IdAssingmentPolicy</CODE> that controls how are - object ids assigned. + the lifetime of the POAs that generate the object references + and the <CODE>IdAssignmentPolicy</CODE> that controls how + object ids are assigned. </P> <P> CORBA Objects that can live irrespective of any particular process in which they are created or activated are called - <EM>Persistent Objects</EM>, - likewise, - shorter-lived objects whose life time is bound to the + <EM>Persistent Objects</EM>. + Likewise, + shorter-lived objects whose lifetimes are bound to the lifetime of the POA in which they are created are called <EM>Transient Objects</EM>. - Notice that this has nothing to do with the state of the object, + Notice that this has nothing to do with the state of the object: an application can create transient objects to access some persistent information maintained in a database. For exammple, - such objects can represent a different session or transaction view - of the data, - similarly, some persistent object references may have no state - or no persistent state, - for example, a logging facility is persistent because it is + such objects can represent a different session or transaction view + of the data. + Similarly, some persistent object references may have no state + or no persistent state. + For example, a logging facility is persistent because it is always available, but it may maintain no state or simply cache some state for the current activation. - In general though, + In general, though, objects that have persistent state are accessed throught persistent object references. </P> @@ -100,7 +100,7 @@ <H3>Child POA Creation</H3> <P> - As before we first initialize the ORB, + As before, we first initialize the ORB, and obtain a reference to the Root POA. </P> <PRE> @@ -112,7 +112,7 @@ </PRE> <P> - Next get the <CODE>POAManager</CODE> of the <CODE>RootPOA</CODE> + Next we get the <CODE>POAManager</CODE> of the <CODE>RootPOA</CODE> and use it to activate the <CODE>RootPOA</CODE> </P> <PRE> @@ -131,7 +131,7 @@ poa->create_lifespan_policy (PortableServer::PERSISTENT); </PRE> <P> - and next we create <CODE>IdAssignmentPolicy</CODE> object with + and next we create an <CODE>IdAssignmentPolicy</CODE> object with the <CODE>USER_ID</CODE> value: </P> <PRE> @@ -164,7 +164,7 @@ policies); </PRE> <P>The values which we pass to this <CODE>create_POA</CODE> operation are - the name of the child POA, the POAManager of the child POA and the + the name of the child POA, the POAManager of the child POA, and the <CODE>CORBA::PolicyList</CODE>. We can create a child controlled by a new <CODE>POAManager</CODE> by passing @@ -172,9 +172,9 @@ but commonly the <CODE>POAManager</CODE> of the parent is used. </P> <P>Finally, we can now destroy the life span policy and id assignment - policy objects since they are no longer needed. The + policy objects, since they are no longer needed. The <CODE>create_POA</CODE> operation will make a copy of the objects in the - policy list. And the newly created POA will refer to the copies of the + policy list and the newly created POA will refer to the copies of the objects passed to the <CODE>create_POA</CODE>. </P> <PRE> @@ -228,8 +228,8 @@ std::cout << ior.in () << std::endl; </PRE> <P>As we know already, the final step before a client's request can - get processed would be to run the ORB event loop.And then to destroy - the POA waiting until the destruction terminates. + get processed would be to run the ORB event loop. Last, we destroy + the POA, waiting until the destruction terminates. </P> <PRE> orb->run (); @@ -263,8 +263,8 @@ $ ./server -ORBEndPoint iiop://localhost:12345 > server.ref & </PRE> - <P>Normally the ORB selects a listening endpoint at random, - this is inadequate for applications with persistent object + <P>Normally the ORB selects a listening endpoint at random. + This is inadequate for applications with persistent object references because the references will become invalid if the server restarts in a new listening endpoint. In TAO we can control the listening endpont(s) using the @@ -279,7 +279,7 @@ <A HREF="../Impl-Repo/index.html"> tutorial </A> - we will learn how we can use + we will learn how we can use the <!-- @@ Priyanka: can you add a URL for the document that describes the implementation repository? --> @@ -324,14 +324,14 @@ <!-- @@ Priyanka: check my comments on what a TRANSIENT exception means --> - <P>A CORBA TRANSIENT exception is raised, - this indicates that some of the resources required to perform - the request are not available, - in this case the client ORB cannot find the server on the - expected port number, - without an Implementation Repository the client ORB cannot - locate the server in its new port, - it has to assume that the server is temporarly down, + <P>A CORBA TRANSIENT exception is raised. + This indicates that some of the resources required to perform + the request are not available. + In this case the client ORB cannot find the server on the + expected port number. + Without an Implementation Repository the client ORB cannot + locate the server in its new port. + It has to assume that the server is temporarly down, and could be restarted in the future, thus the TRANSIENT exception. </P> @@ -359,7 +359,7 @@ TAO </A> distribution includes several - <A HREF="../../../../../examples/POA"> + <A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/examples/POA"> examples </A> that illustrate how to use the POA policies. @@ -369,7 +369,7 @@ <address><a href="mailto:pgontla@ece.uci.edu">Priyanka Gontla</a></address> <!-- Created: Wed Mar 1 20:29:59 PST 2000 --> <!-- hhmts start --> -Last modified: Thu May 11 12:27:24 PDT 2000 +Last modified: Sun Apr 1 15:02:23 PDT 2001 <!-- hhmts end --> </body> </html> diff --git a/TAO/docs/tutorials/Quoter/Simple/Server/index.html b/TAO/docs/tutorials/Quoter/Simple/Server/index.html index 3b9d05ebdca..e6af90aa31a 100644 --- a/TAO/docs/tutorials/Quoter/Simple/Server/index.html +++ b/TAO/docs/tutorials/Quoter/Simple/Server/index.html @@ -13,17 +13,17 @@ <h3>Introduction - A very simple server</h3> <P>Now that we know how to implement a - <A HREF="../Client/index.html">simple client</A> we need to + <A HREF="../Client/index.html">simple client</A>, we need to implement a server to test it out. We have to provide implementations for both the <CODE>Stock</CODE> and <CODE>Stock_Factory</CODE> interfaces, - and then create an executable that implements those interfaces. + and then create an executable that incorporates those implementations. </P> <H3>Implementing the <CODE>Stock</CODE> interface</H3> - <P>To keep things simple why don't we implement a <CODE>Stock</CODE> - object with a fixed price, the constructor will receive all the + <P>To keep things simple, let's implement a <CODE>Stock</CODE> + object with a fixed price. The constructor will receive all the parameters: </P> <PRE> @@ -40,7 +40,7 @@ private: }; </PRE> <P>In a server, CORBA objects and functions are implemented and - represented by programming language functions and data. These + represented by programming language data and functions. These programming entities that implement and represent CORBA objects are called <I>servants</I>. <I>Object Adapters</I> link the world of CORBA objects to the world of programming language servants. They @@ -48,23 +48,23 @@ private: references and for dispatching requests to the appropriate servants. </P> - <P>Notice the name of the base class, TAO implements the CORBA 2.2 - specification, that includes the Portable Object Adapter (hence + <P>Notice the name of the base class. TAO implements the CORBA 2.2 + specification, which includes the Portable Object Adapter (hence the POA prefix). This new Object Adapter fixes many problems with the previous versions of the CORBA specification, where the - so-called Basic Object Adapter was used. Unfortunately the + so-called Basic Object Adapter was used. Unfortunately, the specification was ambiguous and lead to incompatible (yet - compliant) specifications. + compliant) implementations. Code based on the POA, and conforming to the CORBA 2.2 - specification is almost completely portable, - the only incompatibilities arise from the names of the - generated header files and and other minors things like that. + specification, is almost completely portable, + the only incompatibilities arising from the names of the + generated header files and and other minor things. Those problems can be easily wrapped in helper classes, and the file names can be controlled through IDL compiler options in most cases. </P> - <P>A server application may contain multiple POA instances. But, all - these server applications have atleast one POA called the <I>RootPOA</I>. + <P>A server application may contain multiple POA instances, but all + server applications have at least one POA called the <I>RootPOA</I>. <P>We have to implement the operations and attributes: </P> <PRE> @@ -88,7 +88,7 @@ Quoter_Stock_i::symbol () throw (CORBA::SystemException) </P> <P>The first question is what are those <CODE>throw()</CODE> specifications doing there? Any CORBA operation or attribute - can raise a <CODE>CORBA::SystemException</CODE> the IDL compiler + can raise a <CODE>CORBA::SystemException</CODE>. The IDL compiler must generate a throw specification that includes the CORBA system exceptions and any user exceptions listed in the <CODE>raise</CODE> clause. In turn, the C++ specification requires @@ -102,22 +102,22 @@ Quoter_Stock_i::symbol () throw (CORBA::SystemException) <P>It is important to copy the strings before returning them, because the ORB will use <CODE>CORBA::string_free</CODE> to release - them. The rationale is that over the network the string must be + them. The rationale is that over the network, the string must be copied anyway, hence, the client must be responsible for releasing the received string. When both client and servers are in the same address space the ORB can optimize the path and invoke the server operation directly, without marshaling or demarshaling. If the - client is going to work with both local and remote servers it - should always expect to own the string, in consequence the server + client is going to work with both local and remote servers, it + should always expect to own the string. In consequence, the server implementation must always allocate a copy and return the copy, because the server-side must also work identically for local and remote clients. The memory management rules in CORBA are a bit subtle, but there are some simple rules to follow: <UL> - <LI>You must make a copy of the memory that you return, the + <LI>You must make a copy of the memory that you return. The caller is going to release it. </LI> - <LI>Conversely, you must release the memory returned to you, the + <LI>Conversely, you must release the memory returned to you. The callee made a copy. </LI> <LI>You don't own the memory that you receive as input @@ -127,19 +127,19 @@ Quoter_Stock_i::symbol () throw (CORBA::SystemException) after you return. </LI> </UL> - The complete memory management rules can be found in Henning and + The complete memory management rules can be found in the Henning and Vinoski book or the CORBA specification. </P> - <P>Typing all this code seems tedious, can't the IDL compiler - help with this? After all it seems like the method declarations + <P>Typing all this code seems tedious. Can't the IDL compiler + help with this? After all, it seems as if the method declarations are completely specified! The answer is yes, TAO's IDL compiler - can generate empty implementations that you can modify, simply + can generate empty implementations that you can modify. Simply use the <KBD>-GI</KBD> option: <PRE> $ $ACE_ROOT/TAO/TAO_IDL/tao_idl -GI Quoter.idl </PRE> - the empty implementations are generated in the + The empty implementations are generated in the <CODE>QuoterI.h</CODE> and <CODE>QuoterI.cpp</CODE> files. Be advised that the <CODE>-GI</CODE> option overwrites these files every time, so it is better to copy your implementation to @@ -186,11 +186,11 @@ Quoter_Stock_Factory_i::get_stock (const char *symbol) <P>So what is that <CODE>_this()</CODE> method? In the POA mapping the client-side stubs and server-side skeletons are not related - through inheritance, you must either explicitly activate the + through inheritance. You must either explicitly activate the servant (your implementation object) or use <CODE>_this()</CODE> to activate it with its default POA. <CODE>_this()</CODE> creates and registers a CORBA object under the RootPOA, and returns the created - object reference for the ne wobject. We will discuss more about + object reference for the new object. We will discuss more about explicit and implicit activation later, but at this point it is important to remove any thoughts about converting pointers to servants to object references or vice-versa, it just does not @@ -199,8 +199,8 @@ Quoter_Stock_Factory_i::get_stock (const char *symbol) <H3>Implementing a CORBA server</H3> - <P>Now that we have all the object implementations in place we - must create the server executable, we start with the ORB + <P>Now that we have all the object implementations in place, we + must create the server executable. We start with the ORB initialization: </P> <PRE> @@ -213,15 +213,15 @@ int main (int argc, char* argv[]) "" /* the ORB name, it can be anything! */); </PRE> - <P>On startup the ORB starts the POA in the {\em holding state}, + <P>On startup, the ORB starts the POA in the {<em>holding state</em>}, where all requests received are not processed until the POA is activated. Meanwhile the requests are stored to some - implementation limit, TAO sets this limit to 0, because queueing + implementation limit. TAO sets this limit to 0, because queueing is a severe source of overhead and unpredictability in real-time systems. </P> - <P>What does this means for us? Well we have to activate the POA, - the process is a bit tedious, first we gain access to the + <P>What does this means for us? Well, we have to activate the POA. + The process is a bit tedious. First we gain access to the RootPOA: <PRE> CORBA::Object_var poa_object = @@ -229,14 +229,14 @@ int main (int argc, char* argv[]) PortableServer::POA_var poa = PortableServer::POA::_narrow (poa_object.in ()); </PRE> - <P>The <CODE>resolve_initial_references()</CODE> is used to bootstrap - all kinds of services, like the Naming Service, the Trading + <P><CODE>resolve_initial_references()</CODE> is used to bootstrap + all kinds of services, like the Naming Service and the Trading Service, but it is also used to gain access to other ORB - interfaces, such as the RootPOA, the Current objects and the + interfaces, such as the RootPOA, the Current objects, and the Policy Managers. </P> - <P>Now that we have gained access to the Root POA we must obtain - its POA manager, the POA managers provide interfaces to activate + <P>Now that we have gained access to the Root POA, we must obtain + its POA manager. The POA managers provide interfaces to activate and deactivate one or more POAs: </P> <PRE> @@ -250,8 +250,8 @@ int main (int argc, char* argv[]) </PRE> <P>The shutdown process is similar to the client side, but now we - must also remember to destroy the POA, putting all the code - above together we get: + must also remember to destroy the POA. Putting all the code + above together, we get: </P> <PRE> int main (int argc, char* argv[]) @@ -291,7 +291,7 @@ int main (int argc, char* argv[]) Quoter::Stock_Factory_var stock_factory = stock_factory_i._this (); </PRE> - <P>next we convert the object reference into an IOR string, so it + <P>Next we convert the object reference into an IOR string, so it can be used by the client: </P> <PRE> @@ -299,7 +299,7 @@ int main (int argc, char* argv[]) std::cerr << ior.in () << std::endl; </PRE> - <P>There is only one final detail, we must run the ORB event loop + <P>There is only one final detail. We must run the ORB event loop to start processing requests from the client: </P> <PRE> @@ -308,16 +308,16 @@ int main (int argc, char* argv[]) <P>There are many details that we have left out from this server, such as how to terminate the event loop, how to perform servant - memory management, orderly deactivation of servants and the fact - is that it is not very flexible. But we have covered a number + memory management, orderly deactivation of servants, and the fact + is that it is not very flexible, but we have covered a number of other things, and more importantly we can test the client now! </P> <H3>Exercise 1</H3> - <P>Flesh out the implementation, you don't have to do it from - scratch, we provide you with the following files: + <P>Flesh out the implementation. You don't have to do it from + scratch, as we provide you with the following files: <A HREF="Stock_i.h">Stock_i.h</A>, <A HREF="Stock_i.cpp">Stock_i.cpp</A>, <A HREF="Stock_Factory_i.h">Stock_Factory_i.h</A> @@ -342,14 +342,14 @@ int main (int argc, char* argv[]) $ server > ior_file $ client file://ior_file MSFT RHAT </PRE> - also test invalid symbols! + Also test invalid symbols! </P> <hr> <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> <!-- Created: Sat Nov 27 15:47:01 CST 1999 --> <!-- hhmts start --> -Last modified: Thu Feb 17 16:05:23 PST 2000 +Last modified: Sun Apr 1 15:03:38 PDT 2001 <!-- hhmts end --> </body> </html> |