Petals Getting started - day 3 - Expose a FTP Service in SOAP

Version 24 by Mathieu Lebreton
on Nov 09, 2010 12:15.

<< Changes from 23 to 24

compared with

Version 25 by Mathieu Lebreton
on Nov 09, 2010 16:27.

Changes from 25 to 26 >>

Key

This line was removed.

This word was removed. This word was added.

This line was added.

Changes (37)

View Page History

...

# Launch Petals Studio.
# Go to *File* *> New > Service Unit Project*.

# Select *Provide > FTP >* *{_}Your_Current_Version{_}* *{_}Your_Current_Version._*

# Click *Next*. It displays the window "FTP Service-Unit - Defines the JBI properties of the service to import."
## *Service Name*: FtpTutorial

# Click *Next > Next*:. It displays the window "FTP Service-Unit - Define the specific properties for this version of the component."

{note}<folder> attribute is written as optionnal in Studio, but it is not. It will be optional in BC-FTP v3, so as soon as it is published, you will not need to specify the folder attribute for the tutorial.{note}
## *Server*: ftp.petalslink.com

...

## *Password*: demo
## *Folder*: /

## *Transfer Type*: auto
## *Connection Mode*: active

# Click *Finish*.

# Look the generated _jbi.xml_ component configuration. It should look like:
{code:lang=xml|title=jbi.xml}<jbi:provides
interface-name="generatedNs:FtpInterface"
service-name="generatedNs:FtpTutorial"
endpoint-name="FtpTutorialEndpoint">

# Look the source of generated _jbi.xml_, which defines component configuration. The provide section should look like:
{code:lang=xml|title=jbi.xml}     <jbi:provides
           interface-name="generatedNs:FtpInterface"
           service-name="generatedNs:FtpTutorial"
           endpoint-name="FtpTutorialEndpoint">

           
           <petalsCDK:timeout>30000</petalsCDK:timeout>
           <petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
           <petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
           <petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
           <petalsCDK:forward-attachments>false</petalsCDK:forward-attachments>
           <petalsCDK:wsdl>FtpService.wsdl</petalsCDK:wsdl>

           
           <ftp:server>ftp.petalslink.com</ftp:server>
           <ftp:port>21</ftp:port>
           <ftp:user>petals</ftp:user>
           <ftp:password>demo</ftp:password>
           <ftp:folder>/</ftp:folder>
           <ftp:filename>auto</ftp:filename>
           <ftp:transfer-type>auto</ftp:transfer-type>
           <ftp:connection-mode>active</ftp:connection-mode>
           <ftp:delete-processed-files>false</ftp:delete-processed-files>
           <ftp:overwrite>false</ftp:overwrite>
       </jbi:provides>{code}

<\!-\- CDK specific elements -->
<petalsCDK:timeout>30000</petalsCDK:timeout>
<petalsCDK:validate-wsdl>true</petalsCDK:validate-wsdl>
<petalsCDK:forward-security-subject>false</petalsCDK:forward-security-subject>
<petalsCDK:forward-message-properties>false</petalsCDK:forward-message-properties>
<petalsCDK:forward-attachments>false</petalsCDK:forward-attachments>
<petalsCDK:wsdl>FtpService.wsdl</petalsCDK:wsdl>

<\!-\- Component specific elements -->
<ftp:server>ftp.petalslink.com</ftp:server>
<ftp:port>21</ftp:port>
<ftp:user>petals</ftp:user>
<ftp:password>demo</ftp:password>
<ftp:folder>/</ftp:folder>
<ftp:transfer-type>auto</ftp:transfer-type>
<ftp:connection-mode>active</ftp:connection-mode>
</jbi:provides>{code}

# Look the generated _FtpService.wsdl_ sources. Operations available on service are described here.
# Go in *Service-Unit Project* on the left *Petals projects* tree.
# Right click on *"su-FtpTutorial-provide"*.

# Just look the generated _FtpService.wsdl_ sources. Operations available are described here.
# Right click on *su-FtpTutorial-provide* folder, which is in *Service-Unit Project* section on the left *Petals projects* tree.

# Select *Petals > Fast Export for Petals*.

{note:title=Known bug for Studio v1.1.0 !}Please check jbi.xml and FtpService. There is a bug sometimes (on Windows 7).
"interface-name" attribute in _jbi.xml_ and "portType name" in the WSDL should have the same value. If not, please correct _FtpService.wsdl_ :
# SELECT:
<wsdl:portType name="Ftp">
# REPLACE BY:
<wsdl:portType name="FtpInterface">

# Drop (or Copy-Paste) the generated file _sa-FTP-FtpTutorial-provide.zip_ to ./_petals-platform-xxx/install/_ folder to deploy it.
# Check Petals ESB traces to be sure the SA was deployed successfully. (Note: BC-FTP needs to be deployed before deploying your Service-Unit)

This is a known bug in Petals Studio 1.1.0. It might be corrected in version 1.1.1.{note}
# Drop the generated _sa-FTP-FtpTutorial-provide.zip_ to ./_petals-platform-xxx/install/_ folder to deploy it.
# Check Petals ESB traces to be sure the SA was deployed successfully.

h2. Test and monitor in Webconsole

*Send test DIR Operation on root folder:*

# Start the Webconsole.

# Go to *Webconsole > Server:0 > Test > Send*.

# Click *Refresh Domain*.

# Select:
## *Endpoint*: FtpTutorialEndpoint

...

# Go to *Webconsole > Server: 0 > Monitoring > Server Monitoring*.
# Check *Filter endpoint*.

# Select *Endpoint* "FtpTutorialEndpoint"

{info} You can also create filters based on Interface name, Service Name or Operation Name. This is useful for example if one service is duplicated on multiple endpoints.{info}
# Click *Submit*. "FtpTutorial" is now visible in exchange filters list.

# In the exchange filters list, Click the small icon in "Monitoring" column in the list, to activate monitoring for "FtpTutorialEndpoint".

# Go to *Test > Send* panel.

# Send a few test messages from the test panel.

# Go to: *Monitoring > Filter Monitoring*.

# Click the chart icon in *Charts* column.

!Webconsole-monitoring.png|thumbnail,border=1!

_Screenshot: Message exchange monitoring_

_Message exchange monitoring page_
# Go back to previous page in your browser.
# Click the "*+*" button in front of "FtpTutorialEndpoint". You get message exchange details.
# In *Exchange IDs* list, Click the magnifier icon in *Details* column, for the first exchange ID.
# It displays *Exchange global view* page. Just give it a look and try to understand.

*Change destination folder:*

# Got to *[ftp://ftp.petalslink.com]* in your web browser or ftp client, using previous login. You see there is an "Integration" folder. Let's go there.

# Go to *Petals Studio*.

# Edit FtpTutorial's _jbi.xml._

# Replace "<folder>/</folder>" by with "<folder>Integration</folder>"

# Save.

*Redeploy the component:*
# Go to *Webconsole > Server: 0 > Administration > Service-Assemblies*.

# Uninstall the previous FtpTutorial SA: Click *Stop* then *Shutdown* then *Uninstall*).

# Click *Stop* then *Shutdown* then *Uninstall* to uninstall previous "FtpTutorial" SA.

{info}As for installing, you can use three methods:
* from Webconsole: Click alternatively *Stop*, *Shutdown* and *Uninstall* (Alternatives: "force undeploy" or "clear all")

...

* from Command Line: Type _hu_ or _hotundeploy_. Ex: _"hu sa-FTP-FtpTutorial-provide.zip{_}_"._
{info}

# Go to: Petals Studio.

# Well, Click *Clear all*. That's better. Service-Units from day-2 won't be useful anymore, let us clean.
# Go to *Petals Studio*.

# Fast-export the FTP Service-Unit.
# Drag&Drop the newly generated _sa-FTP-FtpTutorial-provide.zip_ from Eclipse to _./petals-platform-xxx/install/_
# Check in Petals ESB traces that the new SA was deployed sucessfully.

# Test FTP Service-Unit by calling DIR operation on Webconsole.
{info:title=Want to go further?}Try reading the files you listed. Look at the BC-FTP Documentation and go on your own. (note that your ftp session is read-only, if you want to call writing operations, create your own ftp server).{info}

# Go to *Webconsole > Server: 0 > Test > Send*.
# Click *Refresh Domain*.
# Send a message to *FtpTutorialEndpoint*, with DIR operation.
# You should see the file "HelloWorld.txt", along with some other files.
{info:title=Want to go further?}Try reading "HelloWorld.txt" using BC-FTP. Look at the BC-FTP Documentation and go on your own. (note that ftp.petalslink.com is read-only. If you want to call writing operations, create your own ftp server).{info}

h2. Expose the FTP service over SOAP

Before, SOAP was used to import WSDL to create services inside Petals ESB. Meaning _Provide_ a SOAP service inside the bus.
This time you will do the contrary : A service (FTP) exists inside the bus. You will create a SOAP Service-Unit to _Consume_ the existing "FtpTutorial" Service. This will expose "FtpTutorial", and make it accessible over SOAP protocol.

BC-SOAP previously imported external WSDL to _Provide_ a service inside Petals ESB.
This time you will expose an existing service (FtpTutorial), from the bus to the outside. BC-SOAP will _Consume_ "FtpTutorial" and expose it as an external SOAP web-service.

...

*Find the WSDL URL:*

# You just deployed _sa-SOAP-FtpTutorial-consume_. Look at Petals ESB traces. Among the last messages, find one similar to the one following. And find the root URL, here "http://127.0.0.1:8084".
{code}[Petals.Container.Components.petals-bc-soap]-INFO 2010-10-06 15:26:22,032 The Axis2 service 'SoapFtpTutorial' has been registered and is available at 'http://127.0.0.1:8084/petals/services/SoapFtpTutorial'{code}

# Go to *[http://127.0.0.1:8084]* in your web browser. It displays a page dedicated to "Petals BC SOAP".

# Go to *Service List*.

# Copy the SoapFtpTutorial WSDL URL.

# Copy the URL of "SoapFtpTutorial" WSDL. (It migh be: http://127.0.0.1:8084/petals/services/SoapFtpTutorial?wsdl)

*Create a SOAP UI Project:*

...

# Launch SOAP UI.
# Click *File > New soapUI Project*.
## *Project Name*: PetalsFtpTutorial (or whatever name).
## *Initial WSDL/WADL*: Paste the WSDL URL previously copied. Might be: [http://127.0.0.1:8084/petals/services/SoapFtpTutorial?wsdl|http://127.0.0.1:8084/petals/services/SoapFtpTutorial?wsdl_]
# Click *OK*.

*Test the proxified FTP DIR operation:*
# Click *PetalsFtpTutorial > FtpServiceSoapBinding > dir*.
# Right click on *Request1*.
# Select *Show Request Editor*: It displays a window with a pre-generated message.
# Delete what is under  <\!\--Optionnal-\->. This means deleting <connection> node and its children.

{info}Ftp parameters are already configured in the Service-Unit, so you do not need to configure them again.{info}

{code:lang=xml|title=Your message looks like this}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://petals.ow2.org/components/ftp/version-3">
<soapenv:Header/>
<soapenv:Body>
<ver:dir>
</ver:dir>
</soapenv:Body>
</soapenv:Envelope>
{code}
# Clic the green arrow to send the message. The response should list several files.
{info:title=Want to go further?}Try reading "HelloWorld.txt" into "Integration" folder, using optional elements instead of deleting them.
\\
You need to redefine ALL properties in this case.
{info}

*Technical monitoring with Webconsole:*
# Go to *Webconsole > Server: 0 > Monitoring > Server Monitoring*
## Check *Filter Endpoint*.
## Select *FtpTutorialEndpoint.*
# Click *Submit.*
# Click the small image in the "Monitoring" column to activate _FtpTutorialEndpoint_ monitoring.
# Send a few test message with SOAP UI.
# Go to *Webconsole > Server: 0 > Monitoring > Filter Monitoring.*
# Click on the magnifier image on the right of any message exchange to get details. You should get a screen like this:
!Exchange SOAP-FTP.png|thumbnail,border=1!
_Screen: Message exchange status_

{info}You can see the message was sent by BC-SOAP to BC-FTP{info}

*DONE. Bravo\!*
Now you know how to:

* Connect Petals ESB to an FTP Server and call operations.
* Monitor service exchanges in Webconsole.
* Expose a Petals Service as external SOAP Web-service.
* Test a web-service with soapUI.

This was more "real" usecase, hum ? Difficulty goes increasing, your knowledge as well.

*Tomorrow you will create a Petals service based on a custom Java class (annotated JSR 181)*

Quick access

Petals Webconsole

Petals View

Petals Studio

Petals Master

Petals ESB

Petals Getting started - day 3 - Expose a FTP Service in SOAP

Changes (37)