Se= nding requests to an ESB.NET Server

S= ending requests to an ESB.NET Server is fairly straight forward once you understand the concept.

Concept=

E= SB essentially uses an XML based Request/Response mechanism for transferring d= ata between systems. The calls can be synchronous or asynchronous based upon da= ta in the request header.

T= he request/response data format uses the envelope paradigm. An envelope contai= ns some generic header information and some specialized data for each particul= ar request. The transaction specific data is contained in one or more documents and/or attachments that are either in-line with the envelope (documents) or= as external references (attachments). Attachments can also be encoded and contained inline within the envelope, however this is not recommended.=

= Figure 1= Analogy to of ESBEnvelope to conventional “snail mail” envelope containing documents and addressing information.

<= o:p>

T= he diagram above shows the format of the ESBEnvelope in XML and the analogy to a conventional physical envelope used in “snail mail”.=

T= he envelope supplies the encapsulating wrapper, contains as standard some rout= ing information (and potentially a whole swag of other details) and contains ze= ro or more documents, and zero or more attachments.

<= o:p>

= Figure 2= Client sending synchronous = request to ESB server

<= o:p>

T= he document XML shown in the example is for a Member Details Enquiry request.<= o:p>

T= he client creates such a request envelope and sends it off to the server for processi= ng. It receives a similar envelope in response. The envelope is passed around u= sing one of the supported transports (HTTP, SOAP) and potentially others such as SMTP and FTP can be transported if required.

Implementation

T= he envelopes used by ESB are in XML format. The most commonly used envelope is= the ESBEnvelope.

Multiple envelopes are supported & in theory you can write your own envelope add-in to support other systems such= as ebXML & the old BizTalk Jumpstart Kit envelopes (= already supported) etc. Your envelope implementation must implement the IEnvelope interface as defined in ESB.NET.=

<= o:p>

O= nce a request has been created, you send the request off to the ESB server over o= ne of the supported transports. Currently supported transports are:=

Raw HTTP POST
SOAP RPC
SOAP Wrapped Document/L= iteral

<= o:p>

Only Internet standard protocols are used= for transports, even though adding in a DCOM or MSMQ transport would be a trivi= al task in the Microsoft implementation, and RMI or JMS in a J2EE implementati= on, this would break interoperability with other platforms and so is purposely = not a supported external transport (although it is used internally). If clients decide to implement this transport, it will be a one-off implementation that will NOT go back into base, although it can be an add-in to the system & maintained by clients if they choose to do so. They do not need the Core co= de base to do this.

Using the ESB.NET = Client from a .NET CLR client

A= lthough there are numerous implementations available to each platform to send data = over the transports listed above, there are also some ESB client side components that may be used if desired. They are recommended as they provide the most flexible/least amount of work for the clients and are geared & optimised for the ESB data formats & SOAP WSDL interfaces. They usually make client-side development fairly clean & robust.

T= he generic client-side components are:

Envelope object –= used to generate request data & parse response data
Re= questHandlerProxy object - used to send = requests off to the server
Related set of hooks for logging and instrumentation etc.

<= o:p>

T= here are also some custom components that often need to be generated. These encapsul= ate the XML (conforming to a given XSD Schema) that needs to be generated for t= he request & response documents specific to each transaction. These compon= ents are used on both the server side and the client-side. As such, they only ne= ed to be created once. They are usually created on the server side & then handed over to the client side developers, although they can be completely independent for the client & server side if desired.<= /p>

T= hese custom components are generated as follows:

Define the XSD Schema f= or the request & response
Run the XSD Schema file= through the Visual Studio.NET utility ‘XSD.exe’ or equivalent. This will create the XML Serialization classes for you. <= /li>

A= lternatively, some more advanced tools support direct manipulation of the XML documents without any of these wrappers. In such cases, only the XSD need be given to= the clients or implementing service handlers.

I= n addition, the Service Definition for each service needs to be given to implementers. = It is envisaged that in future versions of ESB.NET, a dual interface will be e= xposed to allow give simple client applications a low barrier to entry solution wh= en communicating with the ESB.NET server.

<= o:p>

Flow

O= nce all the components are in place on the client side, the client takes the follow= ing steps to send off a request to the ESB server.

Create an instance of t= he custom components (documents wrapper classes).

<= span lang=3DEN-AU style=3D'mso-ansi-language:EN-AU'>Eg

Dim oDocRq as= new MemberDetailsRq

Populate these objects = with the relevant business data.

<= span lang=3DEN-AU style=3D'mso-ansi-language:EN-AU'>Eg

<= span lang=3DEN-AU style=3D'mso-ansi-language:EN-AU'>oDocRq.MemberDetails.FundID<= /span> =3D “VIVA-CORP”=

<= span lang=3DEN-AU style=3D'mso-ansi-language:EN-AU'>oDocRq.MemberDetails.MemberI= D =3D “16”

Create an instance of t= he generic envelope object (generic 1), and add the object above to it. U= se the AddDocument= () method on the envelope to do this. Set the hea= der information in the envelope to set the destination system and the transaction you wish to execute. You can also override the default ESB server and transport type by setting these values in the envelope head= er.

<= span class=3DGramE>Eg.=

Dim oEnvRq as= new Envelope ‘create a new envelope

<= span class=3DGramE>oEnvRq.A= ddDocument(= new Inl= ineDocument(oDocRq)) ‘Add the document to the envelope=

<= span class=3DGramE>oEnvRq.S= ystemName =3D”SUPERB”

<= span class=3DGramE>oEnvRq.S= ystemVersion =3D”2.0.5”

<= span lang=3DEN-AU style=3D'mso-ansi-language:EN-AU'>oEnvRq.Environment =3D”eben”

<= span lang=3DEN-AU style=3D'mso-ansi-language:EN-AU'>oEnvRq.TransactionName =3D”EnqMemberDetails”

Create an instance of t= he generic RequesthandlerProxy object (generi= c 2), and invoke the ProcessMsgSync= () method, passing it the envelope object contain= ing the business document created above as the input parameter. The respon= se of this method is another envelope object, containing a response busin= ess document in the body of the envelope.

Note that you = can have multiple documents in the envelope. The first (default) document in the envelope is used by the server as part of the key to lookup the transaction= s to invoke for the particular request. Any attachments referenced in the envelo= pe will result in the SOAP request being a binary DIME message including the attachments being sent to the server rather than a standard text/xml messag= e.

<= span class=3DGramE>Eg.=

Dim oRhp as n= ew RequestHandlerProxy

<= span class=3DGramE>oEnvRs =3D oR= hp.ProcessMsgSync(oEnvRq)

Get the response busine= ss document out of the envelope. This has your response data in it. Use t= he GetDocument() method on the envelope to do this. This will give you a class hierarchy representing your response XML Schema. Use these classes to get the information out of the response XML.

<= span class=3DGramE>Eg.=

Dim oDocRs as= MemberDetailsEnquiryRs

<= span class=3DGramE>oDocRs =3D oE= nvRs.GetDocument.GetAsObject(GetType(MemberDetailsEnquiryRs))

<= span class=3DGramE>msgbox oDocRs= .MemberDetails.SurName

Most of the code snippets shown here can = be put into base classes and simplified. In general, the majority of the code emph= asis should be on populating and extracting data from the custom document object= s. The rest can be left out of the bulk of the client code. As you can see, th= ere’s very little client side code involved in constructing and sending a request, and all data is type checked at runtime.=

Using the ESB.NET = Client from a COM and ASP client

U= nfortunately, COM does not directly support operator overloading, constructors with parameters etc. and CLR objects. The CLRçèCOM Interop L= ayer goes part of the way to providing integration between the CLR & COM, however it is not without its problems. As such, = it is recommended that you create a wrapper (using a .NET CLR language) for use w= ith your COM objects. ASP has its own peculiarities when talking to .NET CLR objects and the wrapper approach is recommended for those situations also. =

T= o enable COM support, there are some higher level, less flexible methods for adding = and getting documents out of the envelope. They are:

<= span class=3DGramE>oEnvRq.A= ddDocumentCOM(= oDoc)

<= span class=3DGramE>oEnvRs.G= etDocumentCOM(= oDoc) ‘ requires that you instantiate an instance of the oDoc object=

B= ecause the GetDocumentCOM() method does not take a parameter to specify the obj= ect type, you need to create an instance of the response document. The envelope object will then query its type and deserialize accordingly. There have been issues, however with ASP pages as opposed to p= lain VBScript and COM objects which make the wrapper a recommended approach for = ASP pages using the envelope.

<= o:p>

Other client metho= ds for ESB integration

As mentioned earlier, because of the standards based approach, there are many = ways to compose and send a request to a ESB server. You are in no way required to use the ESB client components, although generally (especially with .NET CLR based languages) they will make development a lot easier. Java clients have similar libraries available to them to compose and send requests.

T= here are 2 implementations of SOAP transports, one for the SOAP Wrapped Document/Literal (recommended) and one for the age= ing SOAP RPC. There is also a transport for raw HTTP.

T= he WSDL definitions for the SOAP services can be acquired by appending a “?WSDL” to the SOAP Transport URL’s.

<= o:p>

ESB Server Transpo= rt URL’s

G= iven an address of a ESB server, the transports can be located at:

<= o:p>

Transport U= RL	Description=
http://<hostname>/ESB/<instance>/CoreInternetTransportAda= ptors/ESBSoapRpcTransport.asmx	ESB.NET SOAP RPC Service
http://<hostname>/ESB/<instance>/CoreInternetTransportAda= ptors/ESBSoapXmlDocTransport.asmx	ESB.NET SOAP Document Service
http://<hostname>/ESB/<instance>/CoreInternetTransportAda= ptors/ESBHTTPTransport.aspx	ESB.NET HTTP Service

<= o:p>

ESB WSDL

Description=

http://<hostname>/ESB/<instance>/CoreInternetTransportAda= ptors/ESBSoapRpcTransport.asmx?WSDL

http://<hostname>/ESB/<instance>/CoreInternetTransportAda= ptors/ESBSoapXmlDocTransport.asmx?WSDL

ESB.NET SOAP WSDL

<= o:p>

ESB Managem= ent	Description=
http://<hostname>/ESB/<instance>/Management/Default.aspx<= /span>	ESB.NET Management Console

<= o:p>

ESB UDDI Se= rver(Development/Testing o= nly)	Description=
Provider	Keystroke IT Australia
Service	ESB SOAP Service

<= o:p>

U= DDI is not currently used in production environments. We already know what the services and endpoints are. There is currently no requirement to setup an internal U= DDI service for this purpose. We will also not publish confidential production information on public UDDI servers. If a requirement for UDDI arises, it wi= ll be a Windows 2003 Advanced Server with UDDI Services enabled.

F= or testing, go to http://uddi.microsoft= .com/, click search & select by one of the criteria specified in the table abo= ve.

W= hen the ESB.NET services are individually made available via WSDL, UDDI registration will be done on those if required. Until then, the Service Definitions shou= ld be registered with the UDDI server against the ESB Soap Transport WSDL. Als= o, documentation on how to interpret the Service Definition and create corresp= onding ESBEnvelope requests should be included on the UDDI server.