TAO/docs/ior_parsing.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <!--  -->
   5     <title>Adding new IOR Parsers to TAO</title>
   6   </head>
   7
   8   <body text="#000000" link="#0000ff" vlink="#cc0000" bgcolor="#ffffff">
   9
  10     <CENTER>
  11       <H1>Introduction</H2>
  12     </CENTER>
  13
  14     <h4>What is an IOR Parser?</h4>
  15
  16     <P>TAO supports several IOR formats, including
  17       <CODE>IOR:</CODE>, <CODE>corbaloc:</CODE>,
  18       <CODE>corbaname:</CODE> and <CODE>file:</CODE>.
  19       However, some applications may benefit from other formats, for
  20       example, <CODE>http:</CODE> could allow applications to download
  21       an object reference from a web server.
  22     </P>
  23     <P>Adding new IOR formats to the ORB is a simple task, the ORB
  24       takes advantage ACE's
  25       <A HREF="http://www.cs.wustl.edu/~schmidt/DSEJ-94.ps.gz">
  26         Service Configurator
  27       </A>
  28       to dynamically load new <EM>IOR Parsers</EM>.
  29       The implementation of <CODE>string_to_object()</CODE> queries
  30       each available IOR Parser to convert an string into an object
  31       reference.
  32       Application developers can implement their own parsers and
  33       dynamically (or statically) add them to the ORB, without any
  34       need to recompile TAO.
  35     </P>
  36
  37     <H4>Why aren't the IOR parsers in TAO enough?</H4>
  38
  39     <P>TAO provides a basic set of IOR parsers,
  40       but it would be detrimental to TAO's footprint to implement a
  41       huge collection of IOR parsers into the ORB.
  42       Moreover, the DOC group does not have the ability to create all
  43       possible IOR parsers: many applications will use proprietary
  44       databases to configure the ORB.
  45     <P>
  46
  47     <H4>Why should I use an IOR parser?</H4>
  48
  49     <P>Using an IOR parser is more convenient than, say,
  50       setting up the ad-hoc configuration code in
  51       <CODE>main()</CODE>.
  52       It also allows for easier integration with other TAO components,
  53       such as the <CODE>-ORBInitRef</CODE> options.
  54     </P>
  55
  56     <HR>
  57
  58     <CENTER>
  59       <H1>Implementation</H2>
  60     </CENTER>
  61
  62     <H1>How do you Implement an IOR Parser?</H1>
  63
  64     <P>Implementing an IOR parser is easy,
  65       you must implement a class derived from
  66       <CODE>TAO_IOR_Parser</CODE>.
  67       As an example we will develop an HTTP IOR parser,
  68       the class declaration will probably look like this:
  69 <PRE>
  70 class HTTP_Parser : public TAO_IOR_Parser
  71 {
  72 public:
  73   virtual bool match_prefix (const char *ior_string) const;
  74   virtual CORBA::Object_ptr parse_string (const char *ior,
  75                                           CORBA::ORB_ptr orb,
  76                                           CORBA::Environment &)
  77       ACE_THROW_SPEC ((CORBA::SystemException));
  78 };
  79 </PRE>
  80       For maximal portability this class uses the alternative mapping
  81       for exception handling, if you are not familiar with the
  82       alternative mapping you can safely ignore the
  83       <CODE>CORBA::Environment</CODE> argument.
  84       Please read the exception handling
  85       <A HREF="exceptions.html">
  86         documentation
  87       </A>
  88       for more details.
  89     </P>
  90
  91     <UL>
  92       <LI><B>match_prefix</B> This method must recognize all the IOR
  93         prefixes that this parser supports.  Normally this is a single
  94         prefix, a typical implementation will look like this:
  95 <PRE>
  96 bool
  97 HTTP_Parser::match_prefix (const char *ior_string) const
  98 {
  99   static char http_prefix[] = "http:";
 100   int cmp = ACE_OS::strncmp (ior_string, http_prefix, sizeof(http_prefix));
 101   return (cmp == 0);
 102 }
 103 </PRE>
 104       </LI>
 105       <LI><B>parse_string</B> This method implements the real string
 106         parsing, you can safely assume that the string has been
 107         validated by the <CODE>match_prefix()</CODE> method.
 108         Typically, this method will obtain the IOR string, in our
 109         example by downloading the document from the web server,
 110         and then uses <CODE>string_to_object()</CODE> to return the
 111         object reference:
 112 <PRE>
 113 CORBA::Object_ptr
 114 HTTP_Parser::parse_string (const char *ior,
 115                            CORBA::ORB_ptr orb)
 116 {
 117   // Parse IOR as if it was an http:-URL
 118   ACE_URL_Addr *url_addr =
 119     ACE_URL_Addr::create_addr (ior);
 120
 121   ACE_HTTP_Addr *http_addr =
 122     ACE_dynamic_cast(ACE_HTTP_Addr*,url_addr);
 123
 124   // Connect to the remote host and download the web page, store the
 125   // contents in:
 126   char *document_contents = ...;
 127
 128   return orb->string_to_object (document_contents);
 129 }
 130 </PRE>
 131       </LI>
 132     </UL>
 133
 134     <H4>How do you add an IOR Parser to the ORB?</H4>
 135
 136     <P>As we mentioned above, TAO uses the ACE Service Configurator
 137       framework to find (dynamically or statically) the IOR parsers.
 138       You may want to read the
 139       <A HREF="../../docs/tutorials/022/page01.html">
 140         ACE tutorial
 141       </A>
 142       on this subject, but the process is mostly mechanic, and
 143       described here.
 144     </P>
 145     <P>First you must declare, in the header file, a factory method
 146       and a description of the service,
 147       this is easily accomplished via the following ACE macros:
 148 <PRE>
 149 ACE_FACTORY_DECLARE (Export_Prefix, HTTP_Parser)
 150 ACE_STATIC_SVC_DELCARE_EXPORT (Export_Prefix, HTTP_Parser)
 151 </PRE>
 152       If you are only going to use Unix-like compilers and linkers,
 153       then you can simply use <CODE>TAO</CODE> in place of
 154       <CODE>Export_Prefix</CODE>.
 155       However, under Microsoft Windows variants, this string must be
 156       the prefix of the DLL export/import macros used by your library.
 157       If you are going to statically link your IOR Parser into the
 158       application you will also need to add
 159       <CODE>ACE_STATIC_SVC_REQUIRE</CODE>, as follows:
 160 <PRE>
 161 ACE_FACTORY_DECLARE (Export_Prefix, HTTP_Parser)
 162 ACE_STATIC_SVC_DELCARE_EXPORT (Export_Prefix, HTTP_Parser)
 163 ACE_STATIC_SVC_REQUIRE (HTTP_Parser)
 164 </PRE>
 165     </P>
 166
 167     <P>Next you must implement the services defined above, using some
 168       other group of helper macros, in your source file you should
 169       add:
 170 <PRE>
 171 ACE_STATIC_SVC_DEFINE (HTTP_Parser,
 172                        ACE_TEXT ("HTTP_Parser"),
 173                        ACE_SVC_OBJ_T,
 174                        &ACE_SVC_NAME (HTTP_Parser),
 175                        ACE_Service_Type::DELETE_THIS |
 176                        ACE_Service_Type::DELETE_OBJ,
 177                        0)
 178 ACE_FACTORY_DEFINE (Export_Prefix, HTTP_Parser)
 179 </PRE>
 180       The second argument to <CODE>ACE_STATIC_SVC_DEFINE</CODE> is
 181       the name of the service in ACE's Service Configurator.
 182       It is customary, but not required, to use the name of the class.
 183     </P>
 184
 185     <P>Finally you can dynamically add your IOR parser to the ORB
 186       using the <CODE>-ORBIORParser</CODE> option in the
 187       Resource Factory
 188       (see
 189       <A HREF="Options.html">
 190         Options for TAO Components
 191       </A>
 192       for details about ORB and Resource Factory options),
 193       for example:
 194 <PRE>
 195 # svc.conf file
 196 static Resource_Factory "-ORBIORPaser HTTP_Parser"
 197 </PRE>
 198       would add our new parser to the ORB.
 199     </P>
 200 <PRE>
 201
 202 </PRE>
 203     </P>
 204
 205     <H4>Are there any complete examples?</H4>
 206
 207     <P>Yes, the IOR parsers in the ORB can serve as complete examples,
 208       please check:
 209       <CODE>FILE_Parser.h</CODE>,
 210       <CODE>CORBALOC_Parser.h</CODE>,
 211       <CODE>CORBANAME_Parser.h</CODE>,
 212       or <CODE>DLL_Parser.h</CODE>.
 213       Unfortunately there are no examples that show how to dynamically
 214       add a new IOR parser into the ORB.
 215     </P>
 216
 217     <hr>
 218     <address><a href="mailto:coryan@uci.edu">Carlos O'Ryan</a></address>
 219   </body>
 220 </html>