We Keep Coding

Organizing service responsibilities

I am creating a RESTful web service and I need to map the methods that I want to expose as paths. I got one question regarding the organization of service classes.
Is it normal to create one service class that is the endpoint of the application which internally delegates to other service classes?
And how do you organize methods and paths belonging to a resource? Do you create one MyClassCrudService class, one MyClassOperationsService class etc? And then add that path mapping annotations on each class, or do you create one MyClassResourceService class?
I find it hard to divide the service methods in different classes, and naming them properly.
I could need some guidance on how it is normal to organize the services.

I would recommend starting with one Resource class per logical resource and only adding complexity when necessary. Definining necessary really just takes experience and developing a personal taste or team standard.
If you're new to REST, I would also recommend Bill Burke's RESTful Java with JAX-RS.

External Systems Integration Best Practice

Quick question on what is the best practice for integrating with external systems.
We have a system that deals with Companies which we represent by our own objects. We also use an external system via SOAP that returns a Organization object. They are very similar but not the same (ours is a subset of theirs).
My question is, should we wrap the SOAP service via a Facade so we return only Company objects to our application, or should we return another type of object (e.g. OrgCompany), or even just use the Organization object in our code.
The SOAP service and Organization object are defined by an external company (a bank), who we have no control over.
Any advice and justification is much appreciated.

My two cents, Introducing external objects into application is always a problem. Especially during maintenance. A small service change might lead into big code change in the application.
It's always good to have a layer abstraction between the external service and application. I would suggest to create a service layer which will do the translation of external service object to your application domain objects and use them within the application. A clear separation / decoupling helps a lot in maintenance.
The below diagram depicts the above content.

Your decision here is how you want to manage external code dependencies in your application. Some factors that should play into your decision:
1) How often will the API change, and what's the expected nature of the changes?
2) What's the utility of your application outside its depdencies? If you removed the SOAP service dependency, would your app still serve a purpose?
A defensive approach is to build a facade or adapter around SOAP service, so that your code only depends on your object model. This gives you a lot of control and a relatively loose coupling between your code/logic and the service. The price that you pay for this control is that when the SOAP contract changes, you must also usually also change a layer of your code.
A different approach is to use the objects you're getting from the WSDL directly. This is beneficial when it doesn't make sense to introduce a level of indirection in your application between the client code, i.e. your application is just a feeder into a different system and the whole point of the app is to stuff the Organization object into a JMS pipeline or something similar. If the SOAP API contract never changes and you don't expect the output of your app to change much, then introducing an extra layer of indirection will just hinder the readability of your codebase long term.
Most j2ee developers tend to take the former approach in my experience, both because of the nature of their applications, and wanting to separate their application logic from the details of the data source.
hope this helps.

I can't think of any situation where it's good to use the objects that another company controls. The first thing you should do is bridge those objects into your own. Also, by having your own objects, you can expand their functionality beyond the one that is provided by the third party you connect to (for example if in the future you need to talk to more than one Company object provider)
Look at the Adapter pattern.

I'd support Sridhars suggestion, I'd like just to add that for translating external service objects to your application domain you can use Dozer :
http://dozer.sourceforge.net/documentation/mappings.html

I typically always Adapt externally defined domain objects to an internal representation.
I also create a comprehensive suite of tests against the external domain object, that will highlight any problems quickly if the external vendor produces a new release.

The Enterprise service bus Architecture might be useful here
Its primary use is in Enterprise Application Integration of
heterogeneous and complex landscapes.
(from Wikipedia)
I would check out open source Mule if you are looking for an open source solution

Is there an acceptable way to keep these layers/dependencies separate?

I am currently struggling with whether or not I've achieved a good level of separation, or if I've missed the point somewhere, as I am relatively new to learning the disciplined side of development...
My goal when I started was to create a layer that was agnostic of any persistence mechanism - I called this data-api. I then implemented these interfaces using JDO, and called this project data-jdo. The logic layer ideally talks only is aware of data-api.
This is the point where I'm not sure what makes sense. The business logic layer has to be invoked somehow, right? So is the expectation that the implementation of the data-api (data-jdo, or something else depending on experimentation) is provided (appropriate to say/do injected?) by the invoker?
So the goal would be to (largely for experience and not for productivity) maybe, implement a data-jpa package that could be substituted in place of data-jdo. So the topmost layer (a web service, generic main method as part of a tool, unit tests, whatever) are the ones to make the choice which implementation to use.
Should I be using some framework like Spring to allow me to choose which implementation of my data-api is used, via XML?
Sorry if that's a little vague... I guess the root question is, at what point does the consumer of an API depend on, supply, or become paired with, the implementation of that API? If the answer is or should be "never" then what is used to make sure everything is available at runtime and how does the consumer get an instance of whatever the "API" is describing with only interfaces?

I come from a .net background - not a Java one, so I'm afraid I can't help you with Java specifics.
The business logic layer has to be invoked somehow, right? So is the expectation that the implementation of the data-api (data-jdo, or something else depending on experimentation) is provided (appropriate to say/do injected?) by the invoker?
Yes. In the .Net world I use a Factory (as in an instance of the Factory Pattern) that dynamically returns the data provider implementation (which one of those to use is set by config). The data provider is returned by the factory as an 'object' and it's up to the calling business logic code to cast it to the correct type - as specificed by the interface that the business logic is working against.
I'v egot (another!) article on Dependency Injection for .Net which might help explain with some of the issues, but I'm sure there are good java based ones around somewhere.
Should I be using some framework like Spring to allow me to choose which implementation of my data-api is used, via XML?
Probably. I'd say spend your time getting to grips with the concepts first, worry about "best practice" after that. FYI, I learnt AJAX the hard way - by writting all the code myself. These days I'd run straight to a good framework, but I only think I have the confidence to do that after having really grokked the basics by doing some hard graft at the coal-face :)
... If the answer is or should be "never" then what...
Yeah - it's never. Use a Factory.

Your data-api is a DAO interface layer, that's all your business (aka service) layer should know about persistence. And the presentation layer or any other layer above the business layer shouldn't have any "knowledge" of the DAO layer underneath.
To achieve that, relying on a framework like Spring is a good idea. The top level layer loads an application context which contains all the information for the framework to load the appropriate implementation.
For example, you could load applicationContext.xml from the front-end to use data-jdo, and load testApplicationContext.xml from the unit tests to use data-jpa.

EJB. What is, why it exist and HOW it works?

Guys, I HAVE tried reading tons of stuff about EJB. And I don't get it. It seems that most of the authors have a superficial knowledge on it. They basically say it's the business-logic 'stuff'. They don't show it how it interacts with the AppServer and so on, what it does, how, and why?

It is a huge question, but not that huge. It is not like asking what is physics. You basically run your business code inside container which is handling all the connections, lookup, transactions etc. There are alternatives to ejb, e.g. spring.

The question is huge indeed. EJBs in a general sense try to enforce a design pattern that encapsulates all of your reusable code or "business logic" into a specific tier in your architecture. By doing this you can reuse this code for your web/presentation layer and web services for example. EJBs provide a way of persisting your data to a DB.
The trend in java development now a days is POJO driven architectures that leverage dependency injection. Spring is a popular tool to facilitate this design pattern and I would encourage you to explore this instead of EJB.

an enterprise bean is a server-side component that
encapsulates the business logic of an application. The business logic is the code that fulfills the
purpose of the application. In an inventory control application, for example, the enterprise
beans might implement the business logic in methods called checkInventoryLevel and
orderProduct. By invoking these methods, clients can access the inventory services provided
by the application.

Architecture Concerns

My domain classes and persistance logic (Hibernate) are in one project called model. This jar is included within all of my apps.
Packaged com.company.model & com.company.persistance
Another Utils.jar - contains DateTime, String, Thread, etc general helper classes. This again is included within all of my apps.
Packaged com.company.utils
I have a CXF/Spring app that exposes services for manipulating my data. CRUD functionality, ALL other common functions. This is the 'way in' to my database for any app designed.
Packaged com.company.services and running on Glassfish app server
I have other apps that use the web services (Spring injected) to manipulate my data. Including a web app that will use YUI widgets and the XML/JSON from the web services for a nice smooth UI.
I understand its not really a question! I suppose Im looking for confirmation that this is how others are designing their software. If my architecture makes good, logical sense! Obviously there are security concerns - I will want some applications allowed to only access service x. I will address these later.

Sounds good.
It depends also of the type of application you're developing and the specific requirements for that ( it has to be deployed every week, it has to be deployed in several locations etc )
But so far sounds good enough.
Looks like you can formulate a question from here in the future for some specific scenario.
Since this is not a question, mine is not really an answer. CW

My only comment would be to put the persistence and Hibernate classes into a separate module; so that the model module can be purely beans/POJO/your domain classes.
Here's how I've organized a few multi-module projects before
project-data - contains domain classes and DAOs (interfaces only)
project-services - "Business logic" layer services, makes use of DAO interfaces.
Depends on project-data.
project-hibernate - Hibernate implementation of DAO interfaces.
Depends on project-data.
Conceivably if I were to use some other sort of data-access method I would just create a separate module for that. Client apps could then choose which modules to be dependent on.

Only suggestion I might have is that when you're creating service/models that you group them by subpackage name. ie
com.company.model.core
com.company.service.core
com.company.model.billing
com.company.service.billing
Also, be careful to ensure that no controller code (manipulating your UI) ends up in the services.