Carbon StudioDownloadsDocumentation
Samples
Get InvolvedProject Information![]() |
Shopping Cart SampleContentSample ScenarioThis is a simple shopping cart called Acme where you can purchase items. It contains three views as below.
![]() Download/View Sample Source CodeYou can check-out the latest up-to-date version from here. It contains resources related to several artifact types such as ESB, BPS, Data Services, Gadgets etc.Try the Sample with Carbon Studio
Getting ReadySolution architecture can be described by below diagram. It shows how different WSO2 products helpful in achieving the goal.![]() In this sample, we create five carbon application projects according to artifact type as below. This is just to organize our Eclipse workspace in a user friendly understandable manner.
Create Shopping Cart Data ServiceWe need to create a data service which will represent the legacy database system of the Acme Shopping cart system. With carbon studio, we can create data service artifacts pointing to a data service descriptor file (.dbs) in several ways. In this sample, we will just import the data service descriptor file that we have checked out.Creating Sample Shopping Cart Database If you are planning to deploy data service in to WSO2 Data Services Server 2.5.1, the compatible H2 database version will be H2-1.1.112. As a result, you have to run database scripts which is located inside data-service/sql/h2 against a H2-1.1.112 database. In this sample, we will create sample Shopping Cart Database in a stand-alone H2 database which is compatible with WSO2 DataService 2.5.1 Server. We have provided necessary files and scripts to build the database along with the source. You have to have maven2 installed in your computer in order to do this. To build the database, goto data-service directory inside the source (from command line) execute the following command mvn install It will automatically download necessary files and build the database. After it's completed, you will see a directory named target created inside the current directory. The database is created in ./target/database. In the database descriptor file, you have to specify this database path. It is described in following section. If the database is created successfully, you can move to the next step. Creating Data Service Artifact To create a data service artifact, first we will create a carbon application project called AcmeBackendServices. To create a CApp project, go to File -> new -> project and select Carbon Application Project from the wizard.
Give the name for the project as AcmeBackendServices and a location to save and click Finish.
Now you will see a new project is created with the given name, according to the following structure.
All the artifacts that has been created will be saved in the artifacts folder. To create a data service, right click on the AcmeBackendServices CApp project and select Data Service from the menu.
Now you will get a wizard page, displaying all the options that are available to create a data service artifact.
For this sample, we will select the Import Data Service From File option.Browse the data service descriptor file at the checked-out location under shopping-cart/data-service/dbs folder.
Select the AcmeBackendServices CApp project and click Finish.
Now you will see new Data Service artifact is created under AcmeBackendServices project.
We use this data service to connect with other partners. As a best practice, we do not directly connect to the legacy database system. Created data service will be used when we create ESB configurations later in this sample. To get the service URLs we need to deploy created data service artifact in a server. In this sample we will need several servers running in our setting. As a result, we have to assign different ports to each product to each product to run separately. Here are HTTP and HTTPS ports that we assigned to each products respectively.
We can deploy data service in a WSO2 DSS or any other carbon server which has data service feature installed.You can deploy the data service artifact while you are in your Eclipse workspace. Here, you need to change the JDBC URL property of the database descriptor file to the location of the sample database you created as described above.
You can specify absolute path.
To deploy artifacts in to a server, first thing we have to do is add a WSO2 server. To do that go to Servers view, right click and select New -> Server .
Under WSO2 category, you will see there are two product lines support as carbon 3.0.1 servers (which are already released) and carbon 3.1.x servers (which are currently at the trunk). You can select either option according to the what carbon server you already have. Select WSO2 Carbon 3.0.1 based server and click Next.
If you have not added WSO2 Server instances before, you will need to specify location of the downloaded WSO2 Server instance and click Next.
In the next page specify server ports according to the above table and click Next.
Add and Remove page will list all the CApp projects already in the workspace. Select AcmeBackendServices and click Add.
Now you will see added AcmeBackendServices project is under Configured section. Then click Finish.
At the Servers view, you will see created server is added in the view. Under the server you will see our AcmeBackendServices project is also available.
Before start the server we have to specify that Data Service Artifact should be deployed. To do that double click on the root-artifact.xml and tick ShoppingCartDS from Existing Artifacts.
Now you are ready to start the server. To start the server, right click on the server and select Start from the menu.
Now you will see messages displaying in the console, as you start a normal carbon server.
After carbon server starts, you will see some messages regarding deploying the carbon application project.
Now if you access management console in the normal web browser and go to Service Listing page, you will see, our ShoppingCartDS data service is available.
You can try the service and see for all the available operations that are provided from the data service descriptor file.
EndPoints pointing to the created Data ServiceShoppingCartDS expose three Endpoints which are used by seveal servers when message passing. In this sample we will create three Endpoints as below.
Give the name as AdminServiceEP and select the type Address Endpoint if it is not set by default. Then click Next.
Select AcmeShoppingServices project and AdminServiceEP as the name and click Finish.
Now you will see AdminServiceEP artifact is created under artifacts of the AcmeShoppingServices project.
Double click on the AdminServiceEP.xml and you will see, Endpoint is open in the Graphical ESB Editor and in the Properties view displays all the information regarding the Endpoint. Since we are creating this Address EndPoint according to the simplest template, it will display https://localhost:9443 as the default URI.
You need to change this to the URI of ShoppingCartDS
At the similar manner, create PurchasingServiceEP and ProductServiceEP Endpoints pointing to ShoppingCartDS. You can use the Import EndPoint file from File System option to add all the available Endpoints at once by pointing the Synapse configuration file.
These Endpoints will be used when we create Proxy services to the ShoppingCartDS. Proxy service to created Data ServiceNow we have done all the items needed to create Proxy service to the data service and we are ready to go. For this sample we need to create three Proxy services as below.
Give the name as AdminService and select the option Import Proxy File from the File System. Now browse for the Synapse configuration file (shopping-cart-synapse-config.xml) from the location shopping-cart/esb-config you have checked-out. Now you will see all the available Proxy services are displayed in the table. Select AdminService from the table and click Next.
Specify the project name as AcmeShoppingServices and name as AdminService and click Finish.
Now you will see AdminService Proxy service artifact has been created under artifacts of the AcmeShoppingServices project.
You can double click on the AdminService.xml and open it in the ESB Graphical Editor. You will see AdminServiceEP which we created previously, has been used in the AdminService Proxy service.
You can modify and view all the information regarding a specific mediator by Properties view, which is available whenever you select a node in the tree view. If you are going to try this service after deploy in the WSO2 ESB Server, using try-it functionality, we need to specify WSDL for that. In the checked-out location, under esb-config folder, you can see three WSDL files as AdminService.wsdl, ProductService.wsdl and PurchasingService.wsdl. These three WSDL files are for three proxy services that we are going to create. We have to specify them in respective proxy service as in-line method. I will explain how to specify AdminService.wsdl in the AdminService Proxy Service that we have just created. When you open AdminService Proxy Service in ESB graphical editor, there is a node called WSDL. When you click on that node, under Properties view, you will see available options to add a WSDL. Select in-line from the options.
In the next entry of the Properties view, you have to specify the source of the WSDL file. Click the button at the right hand corner of the Value field and you will see a dialog has been popped up, where you can enter WSDL source.
Open AdminService.wsdl located inside esb-config folder of your checked-out location and copy the content and paste in to popped up dialog and click OK.
Save the configuration. Now you are done with the AdminService Proxy Service. We will create other two Proxy services in the similar manner. Make sure you define the respective WSDL for each proxy service as we did for AdminService proxy service.
All these three Proxy service use Endpoints that we created previously.
Adding dependent resources to registryFor the Proxy services, we need several message transformation files which should be available. With WSO2 Carbon Studio, we can add all these needed resources to registry that is embedded in ESB server. At the location shopping-cart/esb-config which you have checked-out, you will see there are seven xslt files as below.
In the wizard page, you will see there are several ways to create a registry resource. From the four options that are available, select Import from Folder option and browse for the folder that you copy all the xslt files in to and click Next. Select the project as AcmeShoppingServices and give the name as AcmeProxyServiceResources (you may give a name of your preference) and click Finish. Now you will see new Registry Resource artifact is created under Artifacts folder of AcmeShoppingServices project.
Now we have created all the sub parts we need to deploy Proxy service. Before deploying AcmeShoppingServices to WSO2 ESB Server we have to specify which artifacts should be deployed in the root-artifact.xml and other artifact.xml of each artifacts if there are any dependencies. For example AdminService Proxy service depends on AdminServiceEP. This we will specify in the artifact.xml of the AdminService Proxy service. This behavior is similar for other two Proxy services as well.
We will specify three main Proxy services and the AcmeProxyServiceResources registry resource artifact in the root-artifact.xml.
Gadget to Data ServiceNow we have completed representing legacy data system via a Web service and create a Proxy to that service and we can move to front end monitoring section. Data monitoring is done via gadgets. To add gadget related artifacts, we will create a seperate carbon application project named AcmeFrontendMonitor as we created AcmeBackendServices and AcmeShoppingService CApp projects. To create a gadget artifact, right click on the AcmeFrontendMonitor project and select Gadget from the menu.
In this sample, we will import a folder which includes all the resources related to the gadgets we need from the checked-out location. Select Import gadget resource folder from file system option and browse for the location shopping-cart/gadgets/src/gadgets/acme-sales-gadgets/ and click Next.
Select the AcmeFrontendMonitor CApp project and specify the name as AcmeSalesGadgets. Then click Finish.
Now you will see new Gadget artifact called AcmeSalesGadgets is created under AcmeFrontendMonitor CApp project.
When you double click on any of XML files which represent gadget, it will open in the gadget editor provided by Open Social Gadget Editor which gives you a graphical editor to modify gadget files.
Now we will deploy created gadget artifact in to a Gadget Server. With Carbon Studio, you do not have to run all the servers inside Eclipse workspace. You can create a Carbon Archive (.car) file and deploy that in a running server. We will deploy gadget artifact in that way. Extract WSO2 Gadget Server v1.2.0 and go to repository/conf and open mgt-transports.xml and change http and https ports to 9768 and 9448 respectively. Save the changes and start the gadget server. Open the root-artifact.xml of AcmeFrontendMonitor and tick AcmeSalesGadgets artifact and save the changes. To export AcmeFrontendMonitor, right click and select Carbon Application Archive [CAR] from the Export menu.
There is another way to create a carbon archive file. You can select the option from the root-artifact.xml. Open the root-artifact.xml and there is a button to create the Carbon Application Archive [CAR] at the right most top corner.
Then select the artifacts you want to include to the Carbon Application Archive [CAR] and click finish.
Specify the location to save the Carbon Application Archive [CAR] file.
Now you have successfully created a Carbon Application Archive [CAR] file which is ready to be deployed. You can point to the created Carbon Archive from the running gadget server. Go to Add under Applications of the management console.
Browse for the location of the Carbon Archive file and click Upload.
When the upload is done, you will get a message like below.
If you check the console, you will see messages saying that you have successfully deployed the Carbon Archive file.
[2010-10-02 18:37:42,552] INFO - Deploying Carbon Application : AcmeFrontendMonitor-1.0.0.car...
If you go to Browse under Registry Resources tab and go to /_system/config/repository/gadget-server/gadgets, you will see all the gadget xml files that we added. (They will be in /_system/config/repository/dashboards/gadgets if a server other than gadget server, such as greg, is used.) You need to give anonymous user role to the gadget folder, in order to view them in the portal. BPEL to manage scheduled taskIn this sample, we have a schedule task to check whether the products are not out of stock. If a product goes below the re-order limit, message will be sent to operator and suppliers in order to keep all the products are available all the time for the customers. Scheduler task runs periodically and you can change the frequency it needs to be run. Re-order process is a BPEL process which is triggered from ESB Schedule task. Let's try to create re-order process from Carbon Studio. You need to create a BPEL artifact to get the job done. We will create the BPEL artifact under AcmeBackendServices CApp project since it is related to backend services. To create an BPEL workflow, right click on the AcmeBackendServices CApp project and select BPEL Workflow from the menu.
As you can see, there are several ways to create a BPEL Workflow in Carbon Studio. In this sample we will create a new BPEL process pointing to a new BPEL project in the workspace. In the BPEL Workflow creation wizard, select New BPEL Workflow and click Next.
Give the name as ReorderProcess and click Finish.
Now you will get the Eclipse BPEL Designer Plugin BPEL project creation wizard since we select the New BPEL Workflow option. Give the project name as ReorderProcess and click Finish.
Now you will see artifact called ReorderProcess is created under Artifact folder of AcmeBackendServices CApp project and ReorderProcess BPEL project is created in the workspace. This BPEL project is linked from the BPEL artifact.
Now we will import BPEL resources in the location we checked out to the BPEL project in order to create the re-ordering process. To do that right click on the ReorderProcess BPEL project and select Import. Select File System under General category and click Next.
Then browser for the directory shopping-cart/bps/ReOrderProcess/src/ReOrderProcess and tick the ReOrderProcess. Then click Finish.
Now you will see resources regarding to BPEL process is imported to the ReorderProcess BPEL project and same behavior is depicted in the BPEL Artifact at the AcmeBackendServices CApp project.
If you double click on ReOrderProcess.bpel, you will see, it will be opened in the graphical BPEL editor.
Now we will deploy BPEL process in to WSO2 Business Process Server v2.0.1. There are several ways you can deploy created BPEL artifact by Carbon Studio.
Run WSO2 BPS in the ports specified in the table, ie htttp port - 9766 and https port - 9446. Go to Applications of the management console and click Add. Browse for the path of the carbon archive and refresh the page.
Now you will see ReorderProcess has been listed in the service listing page.
If you checked the console, you will see following messages in the console.
[2010-10-03 12:07:13,337] INFO - Process {http://acme.com/shoppingcart/reorder}ReOrderProcess-5 deployed from "{http://acme.com/shoppingcart/reorder}ReOrderProcess-5".
Apache Axis2 Service to Handle message coming from ESBIn this sample, we are going to create two Apache Axis2 services. One service is to handle supplier information and the other service is to notify relavant modules when a purchase has been taken place. First we need to create Eclipse project artifact in order to import them in to the Eclipse workspace. You can find the two projects that includes source files for services at shopping-cart/connector-service and shopping-cart/bps/SupplierService. Go to those folders in the command line and create Eclipse project artifacts running the command mvn eclipse:eclipse. After successfully created Eclipse project artifacts, you can import them in to the Eclipse workspace.
Select Existing Projects into Workspace option under General and click Next.
Browse for the location of the source file of SupplierService and connector-service and click Finish.
Now you will see two projects has been imported to the workspace.
Before creating Apache Axis2 artifacts, make sure you can build imported two projects without any issue. Most of the libraries that needed to resolve class path issues, can be found in {carbon-home}/lib folder of a carbon server, provided that you have run the carbon server atleast for once. Now we are in a position to create two Apache Axis2 service artifacts we need. We will create two Axis2 service in the AcmeBackendServices CApp project. To create an Axis2 Service, right click on the AcmeBackendServices and select Axis2 Service.
You will see there are several ways to create an Axis2 service from Carbon Studio. For this sample, we will browse for the service class and create the Axis2 Service.
In the wizard page, click Browse and type FinanceConnectorService in the Axis2 Service Class dialog and click OK.
Now you will see Fully qualified class and respective project has been filled. Now click Next.
Select the project as AcmeBackendServices and give the name as FinanceConnectorService and click Finish.
In the similar manner, create other Axis2 service from SupplierOrderServiceSkeleton class in the same CApp project.
Now we will deploy these two Axis2 artifacts in to WSO2 Application Server. Extract the downloaded Application Server and change the ports according to the table and run the AppServer as you did for WSO2 BPS and WSO2 Gadget Server. Before creating the Carbon Archive file, double click on the root-artifact.xml and select only the two Axis2 services that we created and save the file. Then export it as a Carbon Archive file.
Add the created Carbon Archive file from the management console of the WSO2 Application Server.
After successfully deploying the Carbon Archive, you will see two new services has been added to the service list.
Create User Portal and Admin PortalIn this sample, there are two Web applications we need to create. One application for the User Portal and the other application for the Admin Portal. Source code for these two portals are at the checked-out location shopping-cart/portal and shopping-cart/admin. Before importing these two projects in to the workspace, make sure that you have successfully built the project and created an Eclipse project archive as well. First we will create the User Portal. Create a Dynamic Web Project by selecting File -> New -> Project -> Web -> Dynamic Web Project
Give the name as UserPortal and keep other options as default and click Finish.
Now you will see an empty Dynamic web project has been created in the workspace.
Now we will import sources from the checked-out location to the UserPortal project that we have created. First we will import the web content. Right click on the WebContent and select Import.
Select File System option and click Next. Browse for the location shopping-cart/portal/src/main/webapp and tick webapp folder and click Finish.
Then we will import Java source files. To do that, go to File -> Import and select File System and browse for shopping-cart/portal/src and set the Into Folder as UserPortal if it is not selected by default.
Build the project and make sure you do not have any build errors. If there are build errors, you may need to add dependent jars to the classpath. If there are no build errors, download axis2-client-1.6.0.wso2v1.jar from here and copy downloaded jar in to WebContent/WEB-INF/lib.
In the similar manner we will create a Dynamic Web Project to create Admin Portal as well. Do not forget to copy axis2-client-1.6.0.wso2v1.jar from here and copy downloaded jar in to WebContent/WEB-INF/lib.
Now we are ready to create Web Applications with the created two dynamic web projects. We will create two Carbon Application projects as AcmeFrontEndUser and AcmeFrontEndOperator. User Portal Web application will be created in AcmeFrontEndUser and Admin Portal Web application will be create in AcmeFrontEndOperator carbon project. First we will create the User Portal Web application. Right click on the AcmeFrontEndUser and select Web Application (WAR) from the menu.
Select Web Application (WAR) from web project option and select UserPortal from the Dynamic Web Project list and click Next.
Select the AcmeFrontEndUser carbon application project and give the name as UserPortal and click Finish.
Now you will see UserPortal Web application artifact is created under AcmeFrontEndUser.
We will deploy created Web application in to a AppServer. Currently, you have to deploy in to a AppServer of Carbon 3.1 server. Double click on the root-artifact.xml of the AcmeFrontEndUser and tick UserPortal and save the file. Now create the Carbon Archive file.
Start the AppServer at the HTTPS port - 9444 and HTTP port - 9764. Add the created CAR by clicking Add under Applications of the management console.
You will get a message like below when the CAR deploying has been done successfully.
Under Web Applications if you click List, it will show all the running Web applications and you will our UserPortal Web application is also listed.
Click Go To URL and you will see our Acme Shopping Cart User Portal.
You can access data from user portal if backend services (i.e Data Service, Proxy Service etc) are up and running. In the similar manner, we will create the other Web application for Admin Portal in the AcmeFrontEndOperator carbon application and deploy it in to the same AppServer.
When the deployment is successful, you will see AdminPortal is also added to Running Web Applications List.
Click Go To URL and you will see the Admin Portal.
|