Shopping Cart Sample

Content

Sample Scenario

This is a simple shopping cart called Acme where you can purchase items. It contains three views as below.
  1. User's view
  2. Operator view
  3. CEO view
User's view provides the ability to search for items, view related products, purchase items etc. There are user level gadgets to display statistics of the products that have been purchased. Operator view facilitate to add new products, edit product details and other operator related functionalities. CEO view contains gadgets that helpful for top level management of the Acme Shopping Cart to take decisions. Acme shopping cart system has a legacy database where it stores information regarding products.



New Server Runtime



Download/View Sample Source Code

You 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 Ready

Solution architecture can be described by below diagram. It shows how different WSO2 products helpful in achieving the goal.



New Server Runtime



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.
  1. AcmeBackendServices - to create all the back-end related artifacts
  2. AcmeFrontendMonitor - to create all front-end gadgets
  3. AcmeFrontendOperator - to create Web application artifact to manage Acme shopping cart
  4. AcmeFrontendUser - to create front-end portal
  5. AcmeShoppingService - to create inter-mediate message passing ESB artifacts

Create Shopping Cart Data Service

We 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.





New Server Runtime







New Server Runtime



Give the name for the project as AcmeBackendServices and a location to save and click Finish.





New Server Runtime



Now you will see a new project is created with the given name, according to the following structure.





New Server Runtime



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.





New Server Runtime



Now you will get a wizard page, displaying all the options that are available to create a data service artifact.





New Server Runtime



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.





New Server Runtime



Select the AcmeBackendServices CApp project and click Finish.





New Server Runtime



Now you will see new Data Service artifact is created under AcmeBackendServices project.





New Server Runtime



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.

Server HTTPS Port HTTP Port
Data Services Server (DS) 9443 9763
Application Server (AppServer) 9444 9764
Enterprise Service Bus (ESB) 9445 9765
Business Process Server (BPS) 9446 9766
Mash-up Server (MS) 9447 9767
Gadget Server (GS) 9448 9768

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.

For example jdbc:h2:file:/home/amila/shoppingcartExample/shopping-cart/data-service/target/database/SHOPPING_CART_SAMPLE_DB

Or you can copy database files to the location of the server and specify the relative path.

For example, if you copy them to $DSS_HOME/samples/database/, The JDBC URL will be,

jdbc:h2:file:./samples/database/SHOPPING_CART_SAMPLE_DB





New Server Runtime



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 .





New Server Runtime



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.





New Server Runtime



If you have not added WSO2 Server instances before, you will need to specify location of the downloaded WSO2 Server instance and click Next.





New Server Runtime



In the next page specify server ports according to the above table and click Next.





New Server Runtime



Add and Remove page will list all the CApp projects already in the workspace. Select AcmeBackendServices and click Add.





New Server Runtime



Now you will see added AcmeBackendServices project is under Configured section. Then click Finish.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



Now you are ready to start the server. To start the server, right click on the server and select Start from the menu.





New Server Runtime



Now you will see messages displaying in the console, as you start a normal carbon server.





New Server Runtime



After carbon server starts, you will see some messages regarding deploying the carbon application project.





New Server Runtime



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.





New Server Runtime



You can try the service and see for all the available operations that are provided from the data service descriptor file.





New Server Runtime



EndPoints pointing to the created Data Service

ShoppingCartDS expose three Endpoints which are used by seveal servers when message passing.

In this sample we will create three Endpoints as below.

  1. AdminServiceEP
  2. ProductServiceEP
  3. PurchasingServiceEP
For the better organization of the workspace, we will create ESB related artifacts in a separate CApp project called AcmeShoppingServices. You can create AcmeShoppingServices project as you created AcmeBackendServices project. To create the Endpoint, right click on the AcmeShoppingServices project and select EndPoint from the right click menu.



New Server Runtime



Give the name as AdminServiceEP and select the type Address Endpoint if it is not set by default. Then click Next.





New Server Runtime



Select AcmeShoppingServices project and AdminServiceEP as the name and click Finish.





New Server Runtime



Now you will see AdminServiceEP artifact is created under artifacts of the AcmeShoppingServices project.





New Server Runtime



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.





New Server Runtime



You need to change this to the URI of ShoppingCartDS





New Server Runtime



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.





New Server Runtime



These Endpoints will be used when we create Proxy services to the ShoppingCartDS.

Proxy service to created Data Service

Now 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.

  1. PurchasingService
  2. AdminService
  3. ProductService
To create a Proxy service, right click AcmeShoppingServices project and select Proxy Service from the menu.



New Server Runtime



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.





New Server Runtime



Specify the project name as AcmeShoppingServices and name as AdminService and click Finish.





New Server Runtime



Now you will see AdminService Proxy service artifact has been created under artifacts of the AcmeShoppingServices project.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



All these three Proxy service use Endpoints that we created previously.





New Server Runtime



Adding dependent resources to registry

For 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.

  1. customer_details_by_email.xslt
  2. decrement_product-stock.xslt
  3. finance_connector.xslt
  4. new_customer.xslt
  5. new_order.xslt
  6. new_order_item.xslt
  7. total_order_amount.xslt
We will copy these seven files to a folder called resources and we will point that folder when we create a Registry Resource Artifact. To create a registry resource, right click AcmeShoppingServices project and select Registry Resource from the menu.



New Server Runtime



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.



New Server Runtime



Select the project as AcmeShoppingServices and give the name as AcmeProxyServiceResources (you may give a name of your preference) and click Finish.



New Server Runtime



Now you will see new Registry Resource artifact is created under Artifacts folder of AcmeShoppingServices project.





New Server Runtime



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.





New Server Runtime







New Server Runtime







New Server Runtime



We will specify three main Proxy services and the AcmeProxyServiceResources registry resource artifact in the root-artifact.xml.





New Server Runtime



Gadget to Data Service

Now 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.





New Server Runtime



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.





New Server Runtime



Select the AcmeFrontendMonitor CApp project and specify the name as AcmeSalesGadgets. Then click Finish.





New Server Runtime



Now you will see new Gadget artifact called AcmeSalesGadgets is created under AcmeFrontendMonitor CApp project.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



Then select the artifacts you want to include to the Carbon Application Archive [CAR] and click finish.





New Server Runtime



Specify the location to save the Carbon Application Archive [CAR] file.





New Server Runtime



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.





New Server Runtime



Browse for the location of the Carbon Archive file and click Upload.





New Server Runtime



When the upload is done, you will get a message like below.





New Server Runtime



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...

[2010-10-02 18:37:42,606] INFO - Successfully Deployed Carbon Application : AcmeFrontendMonitor

[2010-10-02 18:37:53,024] INFO - Successfully populated gadgets from archive ./media/dev/wso2products/RC1/wso2gs-1.2.0/repository/deployment/server/gadgets/AcmeSalesGadgets_1.0.0.dar to the registry.

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 task

In 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.





New Server Runtime



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.





New Server Runtime



Give the name as ReorderProcess and click Finish.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



Then browser for the directory shopping-cart/bps/ReOrderProcess/src/ReOrderProcess and tick the ReOrderProcess. Then click Finish.





New Server Runtime



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.





New Server Runtime



If you double click on ReOrderProcess.bpel, you will see, it will be opened in the graphical BPEL editor.





New Server Runtime



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.

  1. Add WSO2 BPS server and add AcmeBackendServices to it.
  2. Create a carbon archive and deploy it to running BPS server outside.
  3. Export BPEL project via BPEL Exporter Plugin and add it to BPS server running outside.
We will deploy BPEL artifact using the second method as we did for gadget artifact previously. Before we create the carbon archive file, we will open the root-artifact.xml and select only the ReorderProcess artifact to be deployed. This is because we are going to deploy our carbon archive file in to a WSO2 BPS Server. If you have not install features related to data services, previously created ShoppingCartDS artifact will not be deployed. After saving the root-artifact.xml export AcmeBackendServices CApp project as you did for gadget artifact in the previous step.



New Server Runtime



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.





New Server Runtime



Now you will see ReorderProcess has been listed in the service listing page.





New Server Runtime



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".

[2010-10-03 12:07:13,539] INFO - Deploying Axis2 service : ReOrderProcessService

[2010-10-03 12:07:14,018] INFO - Registered process {http://acme.com/shoppingcart/reorder}ReOrderProcess-5.

Apache Axis2 Service to Handle message coming from ESB

In 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.





New Server Runtime



Select Existing Projects into Workspace option under General and click Next.





New Server Runtime



Browse for the location of the source file of SupplierService and connector-service and click Finish.





New Server Runtime







New Server Runtime



Now you will see two projects has been imported to the workspace.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



In the wizard page, click Browse and type FinanceConnectorService in the Axis2 Service Class dialog and click OK.





New Server Runtime



Now you will see Fully qualified class and respective project has been filled. Now click Next.





New Server Runtime



Select the project as AcmeBackendServices and give the name as FinanceConnectorService and click Finish.





New Server Runtime



In the similar manner, create other Axis2 service from SupplierOrderServiceSkeleton class in the same CApp project.





New Server Runtime



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.





New Server Runtime



Add the created Carbon Archive file from the management console of the WSO2 Application Server.





New Server Runtime



After successfully deploying the Carbon Archive, you will see two new services has been added to the service list.





New Server Runtime



Create User Portal and Admin Portal

In 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





New Server Runtime



Give the name as UserPortal and keep other options as default and click Finish.





New Server Runtime



Now you will see an empty Dynamic web project has been created in the workspace.





New Server Runtime



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.





New Server Runtime



Select File System option and click Next. Browse for the location shopping-cart/portal/src/main/webapp and tick webapp folder and click Finish.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



Select Web Application (WAR) from web project option and select UserPortal from the Dynamic Web Project list and click Next.





New Server Runtime



Select the AcmeFrontEndUser carbon application project and give the name as UserPortal and click Finish.





New Server Runtime



Now you will see UserPortal Web application artifact is created under AcmeFrontEndUser.





New Server Runtime



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.





New Server Runtime



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.





New Server Runtime



You will get a message like below when the CAR deploying has been done successfully.





New Server Runtime



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.





New Server Runtime



Click Go To URL and you will see our Acme Shopping Cart User Portal.





New Server Runtime



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.





New Server Runtime



When the deployment is successful, you will see AdminPortal is also added to Running Web Applications List.





New Server Runtime



Click Go To URL and you will see the Admin Portal.





New Server Runtime