aspose file tools*
The moose likes OO, Patterns, UML and Refactoring and the fly likes Newbie - web service design assistance needed Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » OO, Patterns, UML and Refactoring
Bookmark "Newbie - web service design assistance needed" Watch "Newbie - web service design assistance needed" New topic
Author

Newbie - web service design assistance needed

Bo Larson
Greenhorn

Joined: Oct 27, 2008
Posts: 14
I've been following a book that is essentially a tutorial on designing web services, and have been applying it to a specific problem that I need to solve. My question(s) isn't specifically about web services I suppose, just design in general.

The simplified problem is this: I need to expose a product inventory from our ERP system. I'll need two views of this data - one which will be a full inventory list for internal use, and another which will be a subset of inventory items appropriate for public consumption. Ultimately I'm exposing everything via web services.

I've got the technical details out of the way. That is, I've got the data, have some test cases, and even have a little Liferay portlet that shows the public inventory. I'm having a hard time with the design itself though, especially considering that I know this project will increase in magnitude.

So the book had me create a model consisting of classes that are essentially data structures representing my business objects. So I've got InventoryItem, InventoryItemPriceSchedule, and stuff like that. I populate these things via a data access object, so I've got an InventoryDAO interface and an InventoryJdbcDAOImpl concrete class that uses JDBC to pull from my data source.

Now the part(s) where I'm getting confused. The book had me create a "service" package in my project...the word "service" seems to have many meanings... the service interface defines a facade that essentially delegates requests to the DAO interface. The book is calling it a facade here, and I'm not sure if it is. Basically the code looks something like this:



Ok... so I understand how this thing isolates the data layer, but is it a facade if it's just delegating requests to the data layer? The problem with books and tutorials is that they're over simplified. What should this service object...thing... be doing? Should it map requests to the DAO on a one-to-one basis? That seems a little bit silly since I could just not call the InventoryDAO a DAO and just use its interface and skip this layer of abstraction.

I think that the reason the book chose this method might be that there can be multiple implementations of the service... so I might have a facade that uses my Jdbc DAO, and another that uses some other type of data access. (in other words, I have an implementation class that creates the InventoryFacade concrete class and gives it a reference to my DAO concrete class, and returns a new InventoryFacade interface) But I can't imagine why that would ever be necessary in this case.

Finally the book had me create a whole new project which I believe represents my "web service". It calls my InventoryFacade to populate data transfer objects. I generate my web clients from classes in this project.

So here comes the matter of my public vs. internal inventory. In my actual DAO object my method to retrieve items takes an optional list of item numbers to retrieve. Through this mechanism I can specify to only retrieve "public" item numbers, or retrieve all item numbers. Good. But then where do I implement the logic to "only retrieve public items" or "retrieve all items"?

Do I create methods in my InventoryFacade like getEntireInventory() and getPublicInventory()? That would require logic there and I'm not sure if there should be any. Besides, what happens when I want to getSomeOtherSubsetOfInventory()?

So I'm thinking that this logic should go up in the web service itself. Yeah? Nah? What if my list of public inventory items is in the database itself...I would then have to add a method to my facade to getPublicItemNumbers()...which then causes the same problem I mention in my last paragraph: what happens when I want to getSomeOtherItemNumbers()?

And in regards to the web service, the DTOs I'm creating apply to both my public and private web services. How / where do I share them?

I don't think I'm making much sense. I'm holed up in details here even though I've got the functionality working. I just want to figure out how to do this right. I've been away from development for far too long.

Please, any advice would be much appreciated.
Jimmy Clark
Ranch Hand

Joined: Apr 16, 2008
Posts: 2187
Here are a few aspects to think about.

Web services are about integration, not implementation. The process of designing one or more web services is not a replacement for the object-oriented design process of an application or the implementation of a service.

There is a five-layer stack to get familiar with.

Enterprise

Process

Service

Component

Object

At the enterprise level are business services. These are products or servicess that generate revenue. The key is that these services generate money for the business.

At the process level, these are business processes that support the services mentioned above. Each process has a context.

At the service level, these are services that support the business processes above. One service can support many business processes. Or one service can support one business process. This is where web-services are designed.

At the component level, here your existing system can contain components that may or may not be set up to become "web service-fied".

At the object level, this is the implementation of the service. Here are the objects and classes and here is where the object model lives.

Based upon a review of your post, you are mixing up the "services" design with the object-oriented design of the implementation.

To start off, it looks like you can have data-oriented web services to retrieve data from the ERP system.

The application can be designed to call on these services to get data from the ERP system.

So, you will need to come up with an object model design that gets the data. And create a web service that will use this object model as its implementation.

Applications communicate with other applications using "web services".

The only place where "web services" fits in your scenario, is the communication between the Java application and the ERP application.
Here is where you put the "web service". The Java application will communicate and retrieve data from the ERP application using a "web service".

So, everything in the Java application is not a "web service". The Java application will use one or more "web services" to integrate with the ERP system.
[ October 28, 2008: Message edited by: James Clark ]
Bo Larson
Greenhorn

Joined: Oct 27, 2008
Posts: 14
Thank you very much for your detailed reply. I've reviewed it several times.

In the first paragraph of my first post I did mention that my questions might not have anything to do with web services specifically. I guess the only reason that I brought up web services is that the book I happen to be reading uses web services as the basis for its entire implementation from the ground up. And ultimately in my current scope a web service is what I'm after.

So if we completely toss out the idea of a web service, then, I believe that my questions still apply... but maybe I have to rethink them. Here's a try based on your reply:

1)I have an object model that represents the data that I�m working with.
2)I have a data layer that populates the object model from the ERP system.
3)I have a mysterious �service� layer that delegates calls to the data layer. The book I�m referring to calls this service layer a �fa�ade�, and claims that it isolates the data layer from the application? (I think)

Number 3 is one area where I�m confused. First, I thought that a fa�ade presented a simplified set of methods to work with a finer grained layer below it. If this �fa�ade� I�ve got just delegates calls to the data layer, then what is it and what is its benefit?

For example, to work with my model, the code looks something like this:



And the guts of �MyInventoryFacade� look something like this:



So given that, it seems to me that this facade is simple a mechanism to isolate the data layer. Its implementation delegates calls to its DAO on a one-to-one basis, currently. Does that seem correct?

So basically once I've got that (which I do), I implement a web service that uses this model. Where then does your "component" level fit in?

And what comprises a service? Take my case where I need to expose different subsets of my inventory to two different groups. Do I write two web services, one for public consumption and one for internal consumption? They would share some functionality which confuses me... like populating DTOs and retreiving certain pieces of information like when the last time the inventory was updated (our ERP system has a horrible ODBC driver so I wrote some code to recreate and sync portions of it in an external database on a schedule...I run my queries then against the replica).

Perhaps I'm missing something here because I'm using a tool to do some of the work for me. In Eclipse I just choose a class in my "service", which is the "thing" above the model that I'm referring to as a web service, and choose "Create Web Service"...then it does some junk to actually implement the "web service" part of the "web service".

Is the "thing" I'm calling "web service" the missing component level?
Jimmy Clark
Ranch Hand

Joined: Apr 16, 2008
Posts: 2187
Forget what you read in this book and focus on what we are saying for a minute. Below is a revision of your three steps. Does it make sense? If, not what don�t you understand.


1) I have an object model that represents the data that I�m working with.

2) In addition to the �data� part of the object model, you also have business objects that create the �data� objects with data extracted from the ERP system.

3) The business objects extract the data from the ERP system using �web services�. Once the business objects get this data, it uses it to create the data objects.



So, you need to do three things to get this to work. And you will need to create a plan that will outline how you will do these three things.


1) Create the Java classes for the business objects and the data objects.

2) Create a class (named ERPBroker) that will connect to the ERP system and retrieve data of interest.

3) Generate the web service* code that will expose the functionality that the ERPBroker class has.

Once this is ready, the code in the business objects will call the web service (ERPBroker) to get the data from the ERP system.


* ERPBroker is an example of a data-oriented web service. It is called this because it is used to retrieve data. The service has no business logic, it only retrieves data. That is all. This service can be used by multiple applications that need to get data from the ERP system. It can be highly reused and can be integrated into many applications.


So, you will have a web service called ERPBoker. The implementation of this service is coded in a class called ERPBroker.

web service = ERPBroker = Service layer

Java class = ERPBroker = Object layer
[ October 28, 2008: Message edited by: James Clark ]
Bo Larson
Greenhorn

Joined: Oct 27, 2008
Posts: 14
Thank you again for your reply!

You said in #2 that "you also have business objects that create the data objects with data extracted from the ERP", but then in #3 you said "the business objects extract the data from the ERP using 'web services'".

The term "business objects" is confusing me here. There seems to be a contradiction since in #2 I'm reading that the business objects are analagous to data access objects that retreive local data, and in #3 I'm reading that business objects retrieve data from the ERP using web services.

I'm stuck on the part underneath the web service and am not concerned yet about consuming web services.

Are you suggesting that I have two web service layers? One that exposes data in a dumb fashion, and another that consumes the data and then exposes it in a useable way?

I'm sorry if I'm a little bit dense here... maybe if I diagram how I envision it working...

Example:

Human Being -> Client Program (returns view) -> ****WEB**** -> Web Service (returns data transfer objects) -> Inventory Service (returns inventory-specific data objects) -> Data Layer (returns lots of data objects) -> Local Database.
Jimmy Clark
Ranch Hand

Joined: Apr 16, 2008
Posts: 2187
Creating the Java objects and getting the data from the ERP are two different steps.

Step one: get data

Step two: create Java object


In step one, the logic calls the web service to get data. The web service does not return Java objects. The web service returns data.

The logic takes the data and creates the data objects. The business object created the Java objects, not the web service. The purpose of the web service is to return data from the ERP system. It allows the Java application to connect to the ERP system.

Below is an example of updating information in the ERP system.






Example:

Human Being -uses-> Business application

Business application - uses-> Web Service

Web Service -connects to -> ERP application


The business application uses the web service to only get data, not objects. Only data

The web service is the connection between the business application and the ERP application.

There are two applications. The Java application and the ERP application.

And, there is an independent web service.

The web service is used to connect the two applications above.
[ October 28, 2008: Message edited by: James Clark ]
Bo Larson
Greenhorn

Joined: Oct 27, 2008
Posts: 14
I see. I was envisioning the "web service" as being too high up, when it should have been down at what is currently my DAO layer. So basically the web service in this case is just a way of retrieving data to be used by the application.

I'm going to have to let that sink in a little bit.

When is it appropriate to expose higher level constructs as web services? What if I wanted to offer an "Inventory Report" service to be used by remote customers. Would I end up with a web service that ultimately uses another web service for its data source? Won't it almost always end up that way?

Take this scenario:

* I point my browser to a URL inside my local network, and the service residing at that URL generates a nice inventory report and sends it back to my browser.

Solution 1:
I have to have some kind of client application running on that URL, and the client application would understand business objects like inventory reports, and it would ultimately end up calling a web service to retrieve data from the ERP to populate the business objects.

Ok, so what's the benefit of that over:

Solution 2:
I have a dumb client running at the URL that only knows how to display specific data. It retrieves the data by calling a web service. The web service knows all about business objects and sends the appropriate data to the client.

In solution 2, if my business logic changes I don't necessarily have to physically update any of the clients. In solution 1, if I wanted to change some business logic then I would have to physically make sure to update every single client. The only way around that would be to have an intermediate web service that would do the business logic, but then it's more like Solution 2 with a web service for the data layer.
Jimmy Clark
Ranch Hand

Joined: Apr 16, 2008
Posts: 2187
The main purpose of the web service in our example is to �get data from the ERP system�. However, the main objectives of why we would benefit from this service should not be overlooked. First, the service can easily be reused by other applications that need to �get data from the ERP.� Second, the service helps us efficiently integrate two applications with low coupling. The main application of �web services� is to enable remote, distributed computing and serve as a �bridge� between applications.
Our example is a �fine grained�, �data-oriented� web service. Note, there are other types. This is for you to explore.

When is it appropriate to expose higher level constructs as web services?


This is a key aspect of service design. It is not easy to get right. Learn slowly. The opposite of �fine grained� web service is �coarse grained� web service. Take the five layer stack above into consideration. A �Composite Application� is a software application that consists of a group of �business processes� orchestrated with Business Process Execution Language (BPEL) and executed with a Business Process Engine. The business processes are realized by a group of �web services.�

A Composite Application is the implementation of a Enterprise Service. (See more a bottom [Here])

What if I wanted to offer an "Inventory Report" service to be used by remote customers?


If we are talking about HTML/Browser client access, this would not be a �web service�. This would be a web application that generates business reports. The application contains the code that creates the HTML GUI and the report. This would not be valuable as a �web service�. What would be the benefit of having it as accessible as a �web service� instead of a simple HTTP URL to a web page? How would other applications use this type of �web service�? What benefits would you get from having such a "web service". Web services are for connecting applications (integration) not substituting or replacing applications. They are for app-to-app communication. Humans don't call web services. Applications call web services. Humans use distributed applications that may include the usage of web services.

A web application lives on a web sever. This is not a �client application�. This is a �server� application.

The web application, when accessed by a HttpRequest from a browser sends HTML back to the user�s machine.

The web application has the code to present the �reports�. The web application connects to a business application that contains the logic of the application. In this case, the logic consists of taking information provided by the user and getting the data for the report. The business application uses one or more web services to �get data from the ERP system.�

There is no �client� to update. When business logic changes, you change the business logic. That is it. It you want the report to look different, you change the presentation code in the web app.


Or, if you had a Swing/AWT Java application with a GUI that is installed on individual user PCs, then this application might call a "coarse grained" web service that returns the entire inventory report with one call. Here, all the business logic and data processing logic would be in an application and the web service would provide the "gateway" to the application. The client application would call the server application via web service. Here, instead of return just one piece of data, the service will return the entire report.

The role of the web service here, is still to connect the two applications. The one one the client and the one on the server.



What if I wanted to offer an "Inventory Report" service to be used by remote customers?


[*Here]
This could be a service-oriented product or a business service (which is available on the Internet). You would offer the generation of a Inventory Report as a service. Something that someone would pay for. Take note that this is not a "web service."

The implementation of the product would look like something I mention above. Customers wouldn't use this "service" in the same manner as an application calling a web service. They simply would access a web application that generates Inventory Reports. Now, the web application would use web services in the creation of the reports, but it is the web app that generates the report, not a web service.

Hope this helps!
[ October 29, 2008: Message edited by: James Clark ]
Bo Larson
Greenhorn

Joined: Oct 27, 2008
Posts: 14
Thanks! You've been very helpful.

When I mentioned a remote client getting an "inventory report", I didn't mean human being with a web browser, I meant a remote application. Using the word "report" was not appropriate.

I think I'm coming around to what you've told me here; it's starting to make pretty good sense.

Here's a question, though: how do I expose the ERP system via web services without losing the features of the database? I could end up with a thousand little simple queries that essentially just grab table records and then I have to do the "joining" logic manually, or I could end up writing a new function for every specific complex query that I want to perform against the db.

The most reasonable solution almost seems like it would be best to have just one "query" function that takes an SQL query, runs it on the database, and returns some arbitrary table structure. This could prove difficult to secure though.

Ok, so then I have to think: what is the point of using a web service if I just need a database connection? I don't have to go through a bunch of firewalls, and I'm in control of the ones I do, so using HTTP isn't much of a benefit.

And then I need to think about the fact that at this time the database is read-only. I can't put data into the ERP reliably without purchasing special modules from the vendor, and at this time I don't really need to put information in...i just need information out.

The only part of this whole thing that is really interactive is an integration database that I use to map user accounts in a portal to customer numbers in the ERP. Even then, I don't need a web service - I just need a web application that can hit that database. Would you agree?

What I need is a reporting tool and a database connection. I think I've been wasting my time with this web services business. I think maybe I just need BIRT or something similar (simpler?).
Jimmy Clark
Ranch Hand

Joined: Apr 16, 2008
Posts: 2187
Thank you.

Here's a question, though: how do I expose the ERP system via web services without losing the features of the database? I could end up with a thousand little simple queries that essentially just grab table records and then I have to do the "joining" logic manually, or I could end up writing a new function for every specific complex query that I want to perform against the db.


"Features" of the database management system (DBMS) or ERP belong in the system. Your application will have to include such things as security and transaction management, if needed.

Maybe you don't need to use "fine-grained data-oriented web service". Whether or not even having a "web service" for this depends upon your situation. It might be better to just use plain Java objects. It depends.

BIRT is a great tool. It seems appropriate for your needs.

"Web service" design and Service-Oriented Architecture design are very important to understand. If if not for this project, having a good grasp of when and why they apply and don't apply is a good thing.

I suggest a reading of:

Service-Oriented Architecture (SOA) Compass
Hardcover: 272 pages
Publisher: IBM Press
Language: English
ISBN-10: 0131870025
ISBN-13: 978-0131870024

Enjoy!
Bo Larson
Greenhorn

Joined: Oct 27, 2008
Posts: 14
Thank you again so much for your help. I just checked and the book you mentioned is up on Safari so I'll be able to take a look at it soon (Safari is the best).

BTW, I ended up using BIRT. The API is a bit overboard in that you have to create umpteen objects and call a dozen methods just to get it going, but I do have a hacked-together Liferay portlet that is showing BIRT reports. I was able to accomplish in less than eight hours what I had been struggling with for a week or two. And it's nice to be able to visually design reports instead of coding up JSPs. I guess I was just a little overexcited about these concepts that are new to me and wasn't concentrating on finding the simplest solution to the problem. I've read so many articles and have listened to so many podcasts buzzing about SOA and web services that I tried diving in without thinking it through. I really appreciate you taking the time to help me think about how I can appropriately use these technologies when the time arises (and it will, soon).
 
jQuery in Action, 2nd edition
 
subject: Newbie - web service design assistance needed