How to Design and Architect a Java/Java EE web application?

I am java developer with almost 5 years of experience on Struts, Spring and Hibernate.

We have a new project coming up in few days. We have the complete requirements with us and we will be doing this project using Spring MVC, Spring and the Hibernate.

I have been asked to design and architect the entire web application. Designing and creating an Architect is something which I have not done till now in my career. And I don't know how do I go about this and where to start, what tools to use and so on. I don't know even the A,B,C's of design and architecture.

You may be wondering why I was even I asked to do this at first place. The thing is I was given an opportunity to do this and at every stage I will be monitored and I will have my seniors reviewing the design.

So any suggestion, ideas and steps to start and go ahead are welcome.

I can add my 2 cents from my own experiences (although its more of a compilation of development best practises, you might find it useful to keep them in mind while designing your application):

• There is no one-size-fits-all design
• Try to keep application as light weight as possible.
• Use Maven/Gradle to manage dependencies
  • Don't rely excessively on IDE. Make sure your project builds without IDE (If you are using maven/gradle, It will :) Try to open you project with IDEA, Netbeans and Eclipse.
• For the technologies mentioned above, appfuse makes a good starting point.
• Design your database/entities first
• Use libraries sensibly and judiciously. Do NOT overuse them.
• Dont forget to write JUnit/TestNG (at least for service layer)
• Test application on all major browsers (not just your favorite one :)
• Determine how many total users and how many concurrent users your web app will have.
  • Then decide whether you need caching or not.
  • you will use app server clustering or not.
• Select the application server based on its capabilities and more importantly 'your needs'
  • Tomcat / Jetty are absolutely fine for most of the cases
• Avoid using any app-server specific api
• Use JPA interfaces/annotations even if using hibernate as JPA implementation
• Be extra cautious while mapping relationships in entities. Decide which properties and relationships will load lazily and which will load eagerly
• Keep application security in mind while designing the app. Spring security is excellent choice.
• Never abuse HttpSession. Dont store too much in it.
• Keep entities Serializable. Enforce developers to use toString(), hashCode() and equals()
• Dont Forget to use version controlling from Day 1
• Dont just assume that spring/hibernate/spring-mvc will be best choice for you. create small proof of concepts with atleast 3 to 4 options.
• Try to automate integration/build/deploy with CI tools like Jenkins
• Check and Tune SQL generated by Hibernate (time to time)
• Do not let business logic creep into view layer. Hate jsp scriptlets? Consider Velocity/Freemarker. JSP is not the only option.
• externalize the environment specific configuration by using Spring's PropertyPlaceholderConfigurator.
• If possible, try to integrate with existing User Authentication mechanism (Like LDAP/ OpenID) rather than writing your own. This will save you from reinventing the wheel and your users from remembering yet another set of username and password.

There are several things you'll need for architecture design documents. Not an easy task but props on taking the opportunity. Since this is such a large question, hopefully these links can get you started and you can refine questions after getting your feet wet.

Methodology

The methodology you use will affect what tasks you take on first. Waterfall is a popular but outdated methodology. A newer methodology is Agile that has several faces. My favorite is Scrum Agile for developing software of any size.

Diagrams

Diagrams are one of the most powerful ways to represent the system as a whole and as individual components. The type of diagrams you create depend on the system. There are usually a Structure Diagrams, Behavior Diagrams, Interaction Diagrams and tons of others. These diagrams show the pieces of the system as a whole, each components physical layout and/or logical layout, communication flow, procedure flow, etc..

Documentation

Documentation is just like it sounds, documents and documents that have Project Descriptions, Scope, User Cases, Sequence Diagrams, and any other document that describes the project or pieces of the project.

Peruse the Agile Modeling site which pushes for "just enough" modeling. They have some great guidelines including a full "agile modeling process" from requirements gathering to design/development.

http://www.agilemodeling.com/

http://www.agilemodeling.com/essays/amdd.htm

http://www.agilemodeling.com/essays/agileArchitecture.htm

http://www.agilemodeling.com/essays/agileAnalysis.htm

http://www.agilemodeling.com/essays/agileDesign.htm

As for tools, I love Visual Paradigm. It's relatively inexpensive (compared to other tools). There are a variety of free modeling tools (google is your friend), but none compare to Visual Paradigm, and for bit that it costs, it's well worth it. If my employer didn't pony up the cash for it, I would buy it myself... :)

Take a look at Robert Martin's (aka Uncle Bob) Clean Architecture. [Here's](http://blog.8thlight.com/uncle-bob/2012/08/13/the-clean-architecture.html "Clean Architecture") a quick overview. Using this approach, you'll be able to defer details like Spring or Hibernate to a later time and focus more on the business logic. Or even migrate from Spring to Java EE without touching your business and application logic. You'll also get a testable application that complies with the SOLID principles, without too much additional effort.

I've just created an application this way and I must say I'm very happy with it. I could easily port it to a desktop or mobile application, or swap out the storage module. Details depending on policy goes a long way. It also promotes thinking in an API kind of way and, when applied correctly, making your modules very reusable.

Martin goes as far as saying details like frameworks are annoying and not part of your architecture. I do think they belong to architecture, but just at a different level. Often times you do want to include frameworks at an early stage to be able to produce a thin slice of a working application to demo to your users. Or when you know your frameworks in advance and there is no discussion about them, like in my case. But you could regard it as separate software architectures, when combined together create your application architecture.

more details

1. Before embarking on coding get the business requirements down. Build a complete list of requested features, sample screen shots (if available), use case diagrams, business rules etc as a functional specification document. This is the phase where business analysts and developers will be asking questions about user interface requirements, data tier integration requirements, use cases etc. Also prioritize the features based on the business goals, lead-times and iterations required for implementation.

2. Prepare a technical specification document based on the functional specification. The technical specification document should cover: Purpose of the document: e.g. This document will emphasize the customer service functionality. Overview: This section basically covers background information, scope, any inclusions and/or exclusions, referenced documents etc. Basic Architecture: discusses or references baseline architecture document. Answers questions like Will it scale? Can this performance be improved? Is it extendable and/or maintainable? Are there any security issues? Describe the vertical slices to be used in the early iterations, and the concepts to be proved by each slice. Etc. For example which MVC [model-1, model-2 etc] paradigms should we use? Should we use Struts, JSF, and Spring MVC etc or build our own framework? Should we use a business delegate to decouple middle tier with the client tier? Should we use AOP (Aspect Oriented Programming) ? Should we use dependency injection? Should we use annotations? Do we require internationalization? Etc. Assumptions, Dependencies, Risks and Issues: highlight all the assumptions, dependencies, risks and issues. For example list all the risks you can identify. Design alternatives for each key functional requirement. Also discuss why a particular design alternative was chosen over the others. This process will encourage developers analyze the possible design alternatives without having to jump at the obvious solution, which might not always be the best one. Processing Logic: discuss the processing logic for the client tier, middle tier and the data tier. Where required add process flow diagrams. Add any pre-process conditions and/or post-process conditions. UML diagrams to communicate the design to the fellow developers, solution designers, architects etc. Usually class diagrams and sequence diagrams are required. The other diagrams may be added for any special cases. State Chart diagram: useful to describe behavior of an object across several use cases Activity diagram: useful to express complex operations. Supports and encourages parallel behavior. Activity and State chart diagram are beneficial for workflow modeling with multi threaded programming. Collaboration and Sequence diagrams: Use a collaboration or sequence diagram when you want to look at behavior of several objects within a single use case. If you want to look at a single object across multiple use cases then use state chart. Object diagrams: The Object diagrams show instances instead of classes. They are useful for explaining some complicated objects in detail such as highlighting recursive relationships. List the package names, class names, database names and table names with a brief description of their responsibility in a tabular form.

3. Prepare a coding standards document for the whole team to promote consistency and efficiency. Some coding practices can degrade performance for example: Inappropriate use of String class. Use StringBuffer instead of String for compute intensive mutations. Code in terms of interface. For example you might decide the LinkedList is the best choice for some application, but then later decide ArrayList might be a better choice. Wrong approach �� ArrayList list = new ArrayList(); Right approach �� List list = new ArrayList(100); Set the initial capacity of a collection appropriately (e.g. ArrayList, HashMap etc). To promote consistency define standards for variable names, method names, use of logging, curly bracket positions etc.

4. Prepare a code review document and templates for the whole team. Let us look at some of the elements the code review should cover: Proper variable declaration: e.g. instance versus static variables, constants etc. Performance Issues: e.g. Use ArrayList, HashMap etc instead of Vector, Hashtable when there is no thread-safety issue. Memory Issues: e.g. Improper instantiation of objects instead of object reuse and object pooling, not closing valuable resource in a finally block etc. Thread-safety issues: e.g. Java API classes like SimpleDateFormat, Calendar, DecimalFormat etc are not thread safe, declaring variables in JSP is not thread safe, storing state information in Struts action class or multi-threaded servlet is not thread safe. Error handling: e.g. Re-throwing exception without nesting original exception, EJB methods not throwing EJB exception for system exceptions, etc. Use of coding standards: e.g. not using frameworks, System.out is used instead of log4j etc. Design issues: No re-use of code, no clear separation of responsibility, invalid use of inheritance to get method reuse, servlets performing JDBC direct access instead of using DAO (Data Access Objects) classes, HTML code in Struts action or servlet classes, servlets used as utility classes rather than as a flow controller etc. Documentation of code: e.g. No comments, no header files etc. Bugs: e.g. Calling setAutoCommit within container-managed transaction, binary OR “|” used instead of logical OR “||”, relying on pass-by-reference in EJB remote calls, ResultSet not being closed on exceptions, EJB methods not throwing EJBException for system exceptions etc.

5. Prepare additional optional guideline documents as per requirements to be shared by the team. This will promote consistency and standards. For example: Guidelines to setting up J2EE development environment. Guidelines to version control system (CVS, VSS etc). Guidelines to deployment steps, environment settings, ant targets etc. Guidelines for the data modeling (any company standards). Guidelines for error handling. Guidelines for user interface design. Project overview document, Software development process document etc.

There's a good blog post by @tom on reflectoring.io I recently read which may help you. It helped me!

A Checklist for setting up a Java-based Software Architecture

Here are the list of high level topics discussed,

• Architecture Style
• Back-End Concerns
• Frontend Concerns
• Operations Concerns
• Development Concerns

Thanks

I have edited a new book on Spring, Hibernate and Data Modeling which will answer your query on the design aspect of a Java EE web application. Typically a Java EE Web application has 5 tiers - client, presentation, business service, data access and resource(entity). The book focuses on how to design and develop each of these tiers by taking examples of all relationships of data modeling using Spring and Hibernate. As a download an entire web application is given where you would find information on managing each relationship of data modeling scenario.

Let's look at a simple standalone entity. In order to manage the entity, methods like create, read, update, delete and find all records have to be designed. So if we go bottom up, the entity creation forms the first step. Next we look at the Repository which has methods described above. Further up comes the business service tier and then the REST Spring controller which is JSON-based. The remaining task involves coding the JSP page and JQuery AJAX calls to the REST Controller.

You can find more information on the book here