Hi again Petals Padawan. Glad you're on board\!
For your 3rd day, you will connect Petals ESB to a FTP server, and expose the created FTP service as a SOAP web-service, outside Petals ESB.
{panel:title=Last tested with}
* Petals Guide Package 1.0 - [Download binaries here|http://doc.petalslink.com/x/t4KK]
* Tomcat 6.0.29
* JDK 6 update 20
* SoapUI 3.6
This Tutorial uses:
* Petals Studio
* Petals ESB
* Petals SE RMI
* Petals BC SOAP
* Petals Web console
* Tomcat
* Petals BC FTP _(new)_
* soapUI _(new)_
{panel}
Any question, any problem? Find the solution on the [FTP tutorial discussion|http://forum.petalslink.com/Petals-Starting-Guide-day-3-FTP-SOAP-tp2686730p2686730.html].
h2. Deploy a FTP Service Unit
*Install and Deploy BC-FTP:*
# [Download Petals-BC-FTP|http://doc.petalslink.com/x/t4KK] .
# Deploy BC-FTP in Petals ESB.
*Check your access to external FTP server:*
# Go to [ftp://ftp.petalslink.com] in your web browser or with a FTP client.
# Use theses settings:
## *Server*: ftp.petalslink.com
## *Port*: 21
## *User*: petals
## *Password*: demo
# Can you access files ? If yes, perfect\! If not, you will have to build your own local ftp server:
{note:title=If you cannot connect external FTP servers or need to go through an FTP Proxy, create your own local FTP server}
# Create your own local FTP server. Go on your own.
## Some tutorials on Linux: with [vsftpd|https://help.ubuntu.com/6.06/ubuntu/serverguide/C/ftp-server.html] or [gproftpd|http://ubuntuforums.org/showthread.php?p=429783#post429783].
## Tutorial on Windows: with [Filezilla FTP Server|http://lifehacker.com/339887/build-a-home-ftp-server-with-filezilla].
# Unzip [this file|http://doc.petalslink.com/download/attachments/7539609/Petals_FTP_Tutorial.zip] in your FTP folder, to keep similar parameters
# Think to adapt the tutorial to your local FTP. You're smart, that should be pretty easy \;-)
{note}
*Configure and deploy a FTP Service-Unit for* *[ftp.petalslink.com|http://ftp.petalslink.com]**:*
# Start Petals ESB.
# Launch Petals Studio.
# Go to *File* *> New > Service Unit Project*.
# Select *Provide > FTP >* *{_}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."
## *Server*: ftp.petalslink.com
## *Port*: 21
## *User*: petals
## *Password*: demo
## *Folder*: /
# Click *Finish*.
# Look the source of generated _jbi.xml_, which defines the 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">
<!-- 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: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}
# 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*.
# 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 make sure the SA was successfully deployed. (Note: BC-FTP needs to be deployed before deploying your Service-Unit)
h2. Test and monitor in the Webconsole
*Send test DIR Operation on root folder:*
# Start the Webconsole.
# Go to *Webconsole > Server:0 > Test > Send*.
# Click *Refresh Domain*.
# Select:
## *Endpoint*: FtpTutorialEndpoint
## *Operation*: dir
## *MEP*: InOut
# Click *Submit*.
You should get a response message, listing files on the Ftp.
*Monitor services:*
# 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, to activate monitoring for "FtpTutorialEndpoint".
# Go to *Test > Send* panel.
# Send a few test messages.
# Go to *Monitoring > Filter Monitoring*.
# Click the chart icon in *Charts* column.
!Webconsole-monitoring.png|thumbnail,border=1!
_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:*
# Go 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>" with "<folder>Integration</folder>"
# Save.
*Redeploy the component:*
# Go to *Webconsole > Server: 0 > Administration > Service-Assemblies*.
# 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 Autoloader: Remove the corresponding .ZIP package from _./petals-platform-xxx/installed/_
* from Command Line: Type _hu_ or _hotundeploy_. Ex: _"hu sa-FTP-FtpTutorial-provide.zip{_}_"._
{info}
# 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.
# 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 on your own (note that ftp.petalslink.com is read-only. If you want to invoke writing operations, use your own ftp server).{info}
{info:title=Want to go further? SFTP server.}
Petals ESB can connect SFTP servers (FTP over ssh). You can try it. Set up your local SFTP server. Download and install the component Petals-BC-SFTP. Try to configure it to read files on the server.
{info}
h2. Expose the FTP service over SOAP
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.
{info}SU can define service providers or service consumers. The link between a provider and a consumer is virtual. In fact, it is the Petals kernel (and more specifically, the NMR - Normalized Message Router) that will be in charge of putting a consumer and a provider in relation.{info}
*Expose a SOAP-Consume of FtpTutorial:*
# Go to *Petals Studio*.
# Click *File > New > Service-Unit Project*.
# Select *Consume > SOAP > Your_BC-SOAP_Version*.
# Click *Next*. It displays the window "SOAP Service-Unit - You have to provide the namespace".
# Click *Select a service.*
# Select *FtpTutorial implements FtpInterface @ FtpTutorialEndpoint*.
# Click *OK*. Fields are automatically completed.
# Click *Next > Next*. It displays the window "Define the specific properties for this version of the component".
## *Service Name*: SoapFtpTutorial
# Click *Next > Finish*.
# Export and deploy in Petals ESB.
h2. Test with SOAP UI
*Install SOAP UI*:
[Download SOAPUI|http://www.soapui.org/] and install it. SOAP UI is a client to send and receive messages with SOAP protocol.
*Find the WSDL URL:*
# 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 URL of "SoapFtpTutorial" WSDL. (Should look like: [http://192.168.xxx.xxx:8084/petals/services/SoapFtpTutorial?wsdI] \- You can also use: [http://127.0.0.1:8084/petals/services/SoapFtpTutorial?wsdl] )
*Create a SOAP UI Project:*
# Launch *soapUI*.
# Click *File > New soapUI Project*.
## *Project Name*: PetalsFtpTutorial (or whatever name).
## *Initial WSDL/WADL*: Paste the WSDL URL previously copied.
# Click *OK*.
*Test the proxified FTP DIR operation:*
# Click *PetalsFtpTutorial > FtpServiceSoapBinding > dir*.
# Double-click *Request1*. It displays a window with a pre-generated message.
# Delete text with equal or higher indentation than <\!\--Optionnal-\->. This means deleting <connection> node and its children.
{info}FTP parameters are already configured in the Service-Unit _jbi.xml_, 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? Dynamic reconfiguration.}Try reading "HelloWorld.txt" into "Integration" folder, using optional elements in the soapUI message, instead of deleting those elements.
\\
You need to redefine ALL properties.
{info}
*Technical monitoring with Webconsole:*
# Go to *Webconsole > Server: 0 > Monitoring > Server Monitoring*
# Check that monitoring is still activated for "_FtpTutorialEndpoint"._ If not, activate it and send a few test messages with soapUI.
# 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!
_Message exchange status - Message was sent by BC-SOAP to BC-FTP_
\\
*DONE. Bravo\!*
Now you know how to:
* Connect Petals ESB to an FTP Server and call operations.
* Monitor service exchanges in the 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).*
For your 3rd day, you will connect Petals ESB to a FTP server, and expose the created FTP service as a SOAP web-service, outside Petals ESB.
{panel:title=Last tested with}
* Petals Guide Package 1.0 - [Download binaries here|http://doc.petalslink.com/x/t4KK]
* Tomcat 6.0.29
* JDK 6 update 20
* SoapUI 3.6
This Tutorial uses:
* Petals Studio
* Petals ESB
* Petals SE RMI
* Petals BC SOAP
* Petals Web console
* Tomcat
* Petals BC FTP _(new)_
* soapUI _(new)_
{panel}
Any question, any problem? Find the solution on the [FTP tutorial discussion|http://forum.petalslink.com/Petals-Starting-Guide-day-3-FTP-SOAP-tp2686730p2686730.html].
h2. Deploy a FTP Service Unit
*Install and Deploy BC-FTP:*
# [Download Petals-BC-FTP|http://doc.petalslink.com/x/t4KK] .
# Deploy BC-FTP in Petals ESB.
*Check your access to external FTP server:*
# Go to [ftp://ftp.petalslink.com] in your web browser or with a FTP client.
# Use theses settings:
## *Server*: ftp.petalslink.com
## *Port*: 21
## *User*: petals
## *Password*: demo
# Can you access files ? If yes, perfect\! If not, you will have to build your own local ftp server:
{note:title=If you cannot connect external FTP servers or need to go through an FTP Proxy, create your own local FTP server}
# Create your own local FTP server. Go on your own.
## Some tutorials on Linux: with [vsftpd|https://help.ubuntu.com/6.06/ubuntu/serverguide/C/ftp-server.html] or [gproftpd|http://ubuntuforums.org/showthread.php?p=429783#post429783].
## Tutorial on Windows: with [Filezilla FTP Server|http://lifehacker.com/339887/build-a-home-ftp-server-with-filezilla].
# Unzip [this file|http://doc.petalslink.com/download/attachments/7539609/Petals_FTP_Tutorial.zip] in your FTP folder, to keep similar parameters
# Think to adapt the tutorial to your local FTP. You're smart, that should be pretty easy \;-)
{note}
*Configure and deploy a FTP Service-Unit for* *[ftp.petalslink.com|http://ftp.petalslink.com]**:*
# Start Petals ESB.
# Launch Petals Studio.
# Go to *File* *> New > Service Unit Project*.
# Select *Provide > FTP >* *{_}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."
## *Server*: ftp.petalslink.com
## *Port*: 21
## *User*: petals
## *Password*: demo
## *Folder*: /
# Click *Finish*.
# Look the source of generated _jbi.xml_, which defines the 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">
<!-- 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: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}
# 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*.
# 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 make sure the SA was successfully deployed. (Note: BC-FTP needs to be deployed before deploying your Service-Unit)
h2. Test and monitor in the Webconsole
*Send test DIR Operation on root folder:*
# Start the Webconsole.
# Go to *Webconsole > Server:0 > Test > Send*.
# Click *Refresh Domain*.
# Select:
## *Endpoint*: FtpTutorialEndpoint
## *Operation*: dir
## *MEP*: InOut
# Click *Submit*.
You should get a response message, listing files on the Ftp.
*Monitor services:*
# 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, to activate monitoring for "FtpTutorialEndpoint".
# Go to *Test > Send* panel.
# Send a few test messages.
# Go to *Monitoring > Filter Monitoring*.
# Click the chart icon in *Charts* column.
!Webconsole-monitoring.png|thumbnail,border=1!
_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:*
# Go 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>" with "<folder>Integration</folder>"
# Save.
*Redeploy the component:*
# Go to *Webconsole > Server: 0 > Administration > Service-Assemblies*.
# 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 Autoloader: Remove the corresponding .ZIP package from _./petals-platform-xxx/installed/_
* from Command Line: Type _hu_ or _hotundeploy_. Ex: _"hu sa-FTP-FtpTutorial-provide.zip{_}_"._
{info}
# 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.
# 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 on your own (note that ftp.petalslink.com is read-only. If you want to invoke writing operations, use your own ftp server).{info}
{info:title=Want to go further? SFTP server.}
Petals ESB can connect SFTP servers (FTP over ssh). You can try it. Set up your local SFTP server. Download and install the component Petals-BC-SFTP. Try to configure it to read files on the server.
{info}
h2. Expose the FTP service over SOAP
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.
{info}SU can define service providers or service consumers. The link between a provider and a consumer is virtual. In fact, it is the Petals kernel (and more specifically, the NMR - Normalized Message Router) that will be in charge of putting a consumer and a provider in relation.{info}
*Expose a SOAP-Consume of FtpTutorial:*
# Go to *Petals Studio*.
# Click *File > New > Service-Unit Project*.
# Select *Consume > SOAP > Your_BC-SOAP_Version*.
# Click *Next*. It displays the window "SOAP Service-Unit - You have to provide the namespace".
# Click *Select a service.*
# Select *FtpTutorial implements FtpInterface @ FtpTutorialEndpoint*.
# Click *OK*. Fields are automatically completed.
# Click *Next > Next*. It displays the window "Define the specific properties for this version of the component".
## *Service Name*: SoapFtpTutorial
# Click *Next > Finish*.
# Export and deploy in Petals ESB.
h2. Test with SOAP UI
*Install SOAP UI*:
[Download SOAPUI|http://www.soapui.org/] and install it. SOAP UI is a client to send and receive messages with SOAP protocol.
*Find the WSDL URL:*
# 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 URL of "SoapFtpTutorial" WSDL. (Should look like: [http://192.168.xxx.xxx:8084/petals/services/SoapFtpTutorial?wsdI] \- You can also use: [http://127.0.0.1:8084/petals/services/SoapFtpTutorial?wsdl] )
*Create a SOAP UI Project:*
# Launch *soapUI*.
# Click *File > New soapUI Project*.
## *Project Name*: PetalsFtpTutorial (or whatever name).
## *Initial WSDL/WADL*: Paste the WSDL URL previously copied.
# Click *OK*.
*Test the proxified FTP DIR operation:*
# Click *PetalsFtpTutorial > FtpServiceSoapBinding > dir*.
# Double-click *Request1*. It displays a window with a pre-generated message.
# Delete text with equal or higher indentation than <\!\--Optionnal-\->. This means deleting <connection> node and its children.
{info}FTP parameters are already configured in the Service-Unit _jbi.xml_, 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? Dynamic reconfiguration.}Try reading "HelloWorld.txt" into "Integration" folder, using optional elements in the soapUI message, instead of deleting those elements.
\\
You need to redefine ALL properties.
{info}
*Technical monitoring with Webconsole:*
# Go to *Webconsole > Server: 0 > Monitoring > Server Monitoring*
# Check that monitoring is still activated for "_FtpTutorialEndpoint"._ If not, activate it and send a few test messages with soapUI.
# 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!
_Message exchange status - Message was sent by BC-SOAP to BC-FTP_
\\
*DONE. Bravo\!*
Now you know how to:
* Connect Petals ESB to an FTP Server and call operations.
* Monitor service exchanges in the 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).*