cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From h...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/developing web3.xml book.xml
Date Fri, 17 Jan 2003 14:18:03 GMT
haul        2003/01/17 06:18:03

  Modified:    src/documentation/xdocs/developing book.xml
  Added:       src/documentation/xdocs/developing web3.xml
  Log:
  docs for web3
  
  Revision  Changes    Path
  1.12      +4 -0      xml-cocoon2/src/documentation/xdocs/developing/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/developing/book.xml,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- book.xml	1 Jul 2002 19:53:45 -0000	1.11
  +++ book.xml	17 Jan 2003 14:18:02 -0000	1.12
  @@ -23,6 +23,10 @@
       <menu-item label="Developing Webapps" href="webapps/index.html"/>
     </menu>
   
  +  <menu label="Blocks">
  +    <menu-item label="Connect to SAP R/3" href="web3.html"/>
  +  </menu>
  +
     <menu label="Java">
       <external label="API (Javadoc)" href="../apidocs/index.html"/>
     </menu>
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/developing/web3.xml
  
  Index: web3.xml
  ===================================================================
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
  <document>
  	<header>
  		<title>Web3</title>
  		<subtitle>Web3 Connectivity Toolkit</subtitle>
  		<authors>
  			<person name="Michael Gerzabek" email="michael.gerzabek@at.efp.cc"/>
  		</authors>
  	</header>
  	<body>
  		<s1 title="About">
  			<p>
  				<link href="http://www.efp.cc/web3">EFP Consulting Austria</link> produced
an open-source library called Web3
  				that allows you to integrate SAP R/3 seamlessly into Cocoon 2. With these components
you are able to call Remote 
  				Function Calls via an easy to use XML-syntax. For most BAPIs and Remote enabled Function
Calls you simply need 
  				a text editor.
  			</p>
  			<p>This toolkit offers you ...</p>
  				<ul>
  					<li>... synchron communication to any SAP system above release 3.1H.</li>
  					<li>... easy to use ABAP function calls from outside R/3 with a se37-like markup-syntax.</li>
  				</ul>
  			<note>
  				The following guide helps you to setup cocoon with your SAP R/3. Reasonably this guide
cannot answer
  				all questions dealing with your environment. For further questions be advised to contact
your favorite SAP Consultant.
  			</note>
  		</s1>
  		<s1 title="Installing SAP R/3 (TM) JavaConnector">
  			<p>
  					Be sure to proper install the appropriate SAP Java-Connector from <link href="http://service.sap.com/connectors">
  					www.sap.com</link>. To install the connector refer to the included documentations.
  			</p>
  		</s1>
  		<s1 title="Configuring cocoon.xconf">
  			<p>
  					With Web3 you have a flexible Toolkit where you can connect to multiple R/3 System
within one single Cocoon-
  					Instance. Enter your backend configuration into cocoon.xconf like this:
  			</p>
  			<s2 title="Items">
  				<table>
  					<caption>Configuration elements</caption>
  					<tr>
  						<th>Element</th>
  						<th>Description</th>
  					</tr>
  					<tr>
  						<td>web3</td>
  						<td>Declare your logger here.</td>
  					</tr>
  					<tr>
  						<td>pool</td>
  						<td>The pool element is the logical unit of all your SAP settings.</td>
  					</tr>
  					<tr>
  						<td>client</td>
  						<td>The systems client you log onto.</td>
  					</tr>
  					<tr>
  						<td>user, password, language</td>
  						<td>...</td>
  					</tr>
  					<tr>
  						<td>route</td>
  						<td>The route to your SAP system. Please refer to your <link href="http://help.sap.com">SAP
help</link> to prepare the connection string.</td>
  					</tr>
  					<tr>
  						<td>system</td>
  						<td>The system-number of your SAP system you log onto.</td>
  					</tr>
  					<tr>
  						<td>gateway, program-id</td>
  						<td>Are mandatory and not used within Web3's szenario.</td>
  					</tr>
  				</table>
                  <table>
                      <caption>Specifics on the <code>pool</code> element</caption>
  					<tr>
                         <td>@trace</td><td>a <code>boolean</code>
switch whether to use JCO's facility to trace the 	communication layer or not.</td>
                      </tr>
                      <tr>
  					   <td>@level</td><td>if @trace is <code>true</code>
set the trace-level to your prefered value. Please refer to the JCO's documentation about
tracing.</td>
                      </tr>
                      <tr>
  								<td>@size</td><td>denotes the pool-size of your sap connection
pool. Be aware that this is a hard-limited pool.</td>
                      </tr>
  				</table>
  			</s2>
  			<p>
  				A configuration in your cocoon.xconf would look like this:
  			</p>
  
  				<source><![CDATA[<web3 logger="core.web3">
  	<backend name="indy">
  		<pool level="0" size="10" trace="false">
  			<client>100</client>
  			<user>user</user>
  			<password>secret-passphrase</password>
  			<language>DE</language>
  			<route>indy</route>
  			<system>00</system>
  			<gateway>sapgw00</gateway>
  			<program-id>USR-GR02</program-id>
  		</pool>
  	</backend>
  	<backend name="hugo">
  	...
  </web3>]]></source>
  
  		</s1>
  
  		<s1 title="Test the installation">
  			<p>
  				After you configured your Web3 environment you may want to test your connection. In
SAP world there is a typical
  				Remote Function available called RFC_SYSTEM_INFO. It returns some basic configuration
data about your SAP-System.
  				To call this Remote Function point your browser <link href="../../samples/web3/info.xml">here</link>.

  			</p>
  		</s1>
  
  		<s1 title="Implementing your own RFC's">
  			<p>Now that you've established your own Web3-connection you may want to test some
extra Functions. First of all you have
  			to setup your markup with the right Namespace</p>
  			<source><![CDATA[<page xmlns:rfc="http://efp.cc/Web3-Rfc/2.0">
  	...
  </page>]]></source>
  			<p>After doing so you can enter RFC-mappings with the following syntax. You will
see this is a very easy task and you will enjoy
  			using Web3 to do the stuff for you within your SAP environment :)</p>
  			<s2 title="Web3 rfc-Syntax">
  				<p>
  					Data definitions (metadata) are created and managed in the ABAP Dictionary. The ABAP
Dictionary permits a central 
  					description of all the data used in the system without redundancies. New or modified
information is automatically provided 
  					for all the system components. This ensures data integrity, data consistency and data
security.
  				</p>
  				<p>
  					The syntax used within this markup builds upon these facts. So do not wonder if you
find the corresponding logical
  					units in the Cocoon frontend.
  				</p>
  				<table>
  					<caption>Markup</caption>
  					<tr>
  						<th>Element</th>
  						<th>Description</th>
  					</tr>
  					<tr>
  						<td>
  							<link href="#rfc_include">rfc:include</link>
  						</td>
  						<td>Starts a mapping for the specified RFC.</td>
  					</tr>
  					<tr>
  						<td>
  							<link href="#rfc_import">rfc:import</link>
  						</td>
  						<td>Container element for structures and fields.</td>
  					</tr>
  					<tr>
  						<td>
  							<link href="#rfc_tables">rfc:tables</link>
  						</td>
  						<td>Container element for tables.</td>
  					</tr>
  					<tr>
  						<td>
  							<link href="#rfc_structure">rfc:structure</link>
  						</td>
  						<td>Container element for fields.</td>
  					</tr>
  					<tr>
  						<td>
  							<link href="#rfc_table">rfc:table</link>
  						</td>
  						<td>Container element for structures.</td>
  					</tr>
  					<tr>
  						<td>
  							<link href="#rfc_field">rfc:field</link>
  						</td>
  						<td>The data-fields.</td>
  					</tr>
  				</table>
  			</s2>
  
  			<anchor id="rfc_include"/>
  			<s2 title="rfc:include">
  				<p>First when you start to map a RFC keep in mind to get the parameters from your
SAP system. Therefore you
  				may want to use se37 where all relevant parameters are listed. The <code>@name</code>
has to be the name of
  				the RFC you want to map. </p>
  				<p>Since many RFC's return hierarchical data split into tables you will encounter
some
  				problems in xslt when rendering these data to trees. So you may implement <code>org.apache.cocoon.components.web3.Web3Streamer</code>
to get a proper XML to work with. You can set your own streamer in the
  				<code>@streamer</code>.</p>
  				<table>
  					<caption>Attributes</caption>
  					<tr>
  						<th>Attribute</th>
  						<th>Description</th>
  					</tr>
  					<tr>
  						<td>
  							@name
  						</td>
  						<td>The name of the SAP RFC</td>
  					</tr>
  					<tr>
  						<td>
  							@streamer
  						</td>
  						<td>The class-name of your function streamer. Most of the time you won't need
to implement it anyway.</td>
  					</tr>
  				</table>
  				<p/>
  			</s2>
  			<anchor id="rfc_import"/>
  			<s2 title="rfc:import">
  				<p>
  					When requesting a RFC you have to fill the import parameterlist. The import parameterlist
lists all relevant parameters
  					that have to be provided to get proper results from your R/3.</p>
  				<p>se37 can provide you with the relevant information.
  				</p>
  			</s2>
  			<anchor id="rfc_tables"/>
  			<s2 title="rfc:tables">
  				<p>
  					Some highly complex RFC's have also tables in their calling interface. You may need
to read the SAP documentation of the
  					BAPI you gotta call and when to make use of one of them.
  				</p>
  			</s2>
  			<anchor id="rfc_structure"/>
  			<s2 title="rfc:structure">
  				<p>
  					A structure comprises fields. A field can refer to an elementary type (via a data element
or by directly specifying the data type and length in the structure definition), another structure
or a table type. A structure can therefore be nested to any depth.
  				</p>
  					<note>At the time the facility to use nested structures has not been tested!</note>
  			</s2>
  			<anchor id="rfc_table"/>
  			<s2 title="rfc:table">
  				<p>
  					A table consists of a collection of structures with same structure type. To keep it
simple we can sloppily say a table is like
  					a SQL-database-table.
  				</p>
  			</s2>
  			<anchor id="rfc_field"/>
  			<s2 title="rfc:field">
  				<p>
  					Fields, also called data elements are the smallest indivisible units of the complex
types and are used to specify the types 
  					in structures and columns of tables. A field describes either an elementary type or
a reference type.</p>
  				<p>
  					In ABAP exist predefined types and custom defined types. But don't worry about the
horrible task of converting into the right
  					type. This task is excellently done for you by the JavaConnector.
  				</p>
  				<note>
  					Keep in mind that the communication format for numbers and date is US. So supply <code>Date</code>
information
  					in format YYYY-MM-DD with the slashes and <code>number</code> information
like DDDDD.DD where the dot is the comma!
  				</note>
  			</s2>
  			<p>If you want to check your RFC mappings for syntactically correctness you may
want to use the enclosed <code>dtd</code>'s.</p>
  		</s1>
  		<s1 title="A more complex example">
  			<p>
  				The included example demonstrates a more complex function call. Keep in mind that the
correct execution
  				depends on the local customizing settings of the connected SAP System.
  			</p>
  			<source><![CDATA[<page xmlns:rfc="http://efp.cc/Web3-Rfc/1.0">
    <rfc:include name="XXX" streamer="XXX">
      <rfc:import>
        <rfc:structure name="XXX">
          <rfc:field name="XXX">YYY</rfc:field>
          <rfc:field name="XXX">YYY</rfc:field>
          <rfc:field name="XXX">YYY</rfc:field>
        </rfc:structure>
        <rfc:tables>
          <rfc:table name="XXX">
            <rfc:structure name="1">
              <rfc:field name="XXX">YYY</rfc:field>
              <rfc:field name="XXX">YYY</rfc:field>
              <rfc:field name="XXX">YYY</rfc:field>
            </rfc:structure>
          </rfc:table>
        </rfc:tables>
      </rfc:import>
    </rfc:include>
  </page>]]></source>
  		</s1>
  		<s1 title="Setting up the sitemap">
  			<p>There are two ways to setup your Web3Transformer in the sitemap.</p>
  			<s2 title="Global Configuration">
  				<p>If you have to deal only with one R/3 Instance you may
  				configure your <code>org.apache.cocoon.transformation.Web3RfcTransformer</code>
  				global like stated in the following sitemap snippet.</p>
  
                  <source><![CDATA[
  <map:transformer name="rfc" 
                   src="org.apache.cocoon.transformation.Web3RfcTransformer" 
                   logger="web3.transformation">
    <system>indy</system>
  </map:transformer>
  ]]></source>
  				</s2>
                <s2 title="Parametrized Configuration">
  				<p>If you have setup several R/3 pools you can parametrize the
                     <code>org.apache.cocoon.transformation.Web3RfcTransformer</code>
as stated next</p> 
                     <source><![CDATA[
  <map:transform type="rfc">
    <map:parameter name="backend" value="indy"/>
  </map:transform>
  ]]></source>
  			</s2>
  		</s1>
  		<s1 title="Further questions">
  			<p>
  				Enjoy using Web3. For further questions feel free to contact the author <link href="mailto:michael.gerzabek@at.efp.cc">Michael
Gerzabek</link>
  			</p>
  		</s1>
  		<figure src="images/cocoon-built.gif" alt="Built with Apache Cocoon"/>
  	</body>
  </document>
  
  
  

----------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message