gjf architecture best practices

Global Java Capability - Java Architecture Best Practices

[Project/Account/Team (applied by team to all templates)]Global Java Capability - Java Architecture Best Practices [Section if needed]

[Project/Account/Team (applied by team to all templates)]Global Java Capability - Java Architecture Best Practices [Section if needed]

Amendment History - Document Status (e.g. Draft, Final, Release #):

CR# (optional)Document Version#Approval DateModified BySection, Page(s) and Text Revised

1.0010/18/2006T. HealeyFinal Version

This document is permanently stored in the Global Java Community website on knowledgeCentre [12].

Table of Contents

1Introduction

1Purpose

2Scope

2Architecture best practices

2General architecture best practices

3Use Case View best practices

4Logical View best practices

4Process View best practices

5Development View best practices

7Physical View best practices

8Architecture Antipatterns

13References

IntroductionThis document outlines a set of architecture mechanisms, approaches, techniques, and guidelines for building enterprise Java applications as recommend by the AD Global Java Community.

Purpose

The primary purpose of this document is to provide guidance for architecture practices used on -managed software development projects. In this document, architecture refers to high-level design of an application and the processes used to implement it, typically the responsibility of the Application Architect and the Project Manager.ScopeThe scope of this document includes the following:

1. Providing guidelines that will aid experienced architects perform their job.

2. Assisting intermediate level architects and project managers in approaching the set-up and execution of their projects.This document is not meant to address all aspects of enterprise software architecture and is no substitute for skilled and experienced architects. Also, it does not address general project management best practices, which are covered well by CMMI and PMBOK.The recommendations are based on collective experience and general industry practice. Many of the recommendations are not specific to Java.The reader should note that best practices are always dependent on many environmental factors, such as:

Skills and experience of the project team

Whether the team is co-located or geographically dispersed

Available tools, components, frameworks, and infrastructure Project size and criticalityFinally, this catalog is not intended to be complete. It reflects the best practices and worst practices (antipatterns) that we tend to see on the majority of projects we work on. The catalog will need to continually evolve over time as new technologies and practices are encountered.Architecture best practices

Architecture is typically the responsibility of the Application Architect and the Project Manager. We have organized the best practices around the 4+1 model of architecture, employed by GAD QMS Object & Component Engineering (OCE) worktype and Rational Unified Process (RUP). The practices listed in this section are not Java-specific, except as regards the mention of specific tools and frameworks.General architecture best practices1. Iterative Methodology: Most medium-to-large projects should use use a project methodology that explicitly supports iterative and incremental development, such as GAD QMS OCE (Object & Component Engineering) or Rational Unified Process (RUP). Iterations should tend to be shorta few weeks to a couple months at the longest. Do not use a waterfall-based methodology (e.g., DEV+), except on the smallest of projects. [1]2. Technical Launch: On all but the most trivial of projects, conduct a Technical Launch / Risk Assessment activity during project start-up with at least one experienced JEE architect. Review all facets of the project architecture. For further details, refer to the New Zealand CoE RATLA process and associated assets, which can be found by searching for Technical Launch in the Best Practices Repository [20].3. Prototype: Prototype the architecture, particularly in the early iteration(s) of the project. Validate application designs, infrastructure, 3rd party tools, performance, system interfaces, and user interface design early.4. Experienced Architect: The application architecture should be developed and maintained by an experienced Java/OO architect/designer, with a singular vision that avoids unnecessary complexity. Procedural developers (COBOL, C) often make the mistake of creating pseudo-OO designs based on functional decomposition techniques. If using GAD QMS OCE work type, the architect/design team performs the roles of Application Designer, Technical Leader, Application SME, and Object Designer.5. Conform to Appropriate Reference Architecture: The application architecture should be based on a standard JEE reference architecture. Resist the urge to either over- or under-architect; good architecture is about appropriate balance of forces. Consider the following references:

A3 Architecture [3] catalogue of reusable patterns [4] Delivery Systems Architecture (DSA) [5] New Zealand CoE JEE Reference Architecture [22]

Sun's Enterprise Java Blueprints [2]

6. Bake Best Practices into the Project Plan: Best practices do not happen by accidentthey must be integrated into the project plan as a joint exercise by the Architect and Project Manager. For example, there should be a specific task to create the development standards and establish the development environment. As a part of the plan, best practices must also be executed and monitored. Regular feedback cycles (usually at the end of each iteration) should assess how well (or poorly) best practices are being incorporated, and adjustments made as necessary.Use Case View best practices7. Utilize Use Cases: Utilize use cases to document and manage functional user requirements. There are many books and articles that discuss best practices for use cases. For more specific guidance, refer to GJFs OO and UML Best Practices [6]. Going forward, manage use cases using Borland CaliberRM, part of the Application Engineering Toolkit [14].Logical View best practices8. Create UML Diagrams: Utilize UML class diagrams (at minimum) to document the logical structure. These may be sketchy at first (do not detail all method signatures), but should gain detail as the project progresses. Utilize UML diagramming best practices as recommended by the Global Java Capability [6].9. Create E/R Diagrams: Entity/Relationship diagrams should be created showing the structure of the database and relationship of the tables. Most projects use CA ERwin.10. Utilize a Service-Oriented Architecture: Utilize a service-oriented architecture (SOA) based on XML web services for inter- and intra-application interfaces when appropriate. Work out the services and their interactions early; a team-per-service approach works well to formalize and build-out the services and their interfaces.11. Utilize Model-Driven Architecture (MDA) Techniques: Even without a full-blown MDA tool, large gains in productivity and API documentation completeness can be derived by using UML and Javadoc to drive code development. Some (many?) teams create application software specifications in a Microsoft Word-based format, which is extremely inefficient and error-prone. The project should instead first create designs in UML, then use the UML tool to create Java class/method stubs. Most IDEs can then generate Javadoc from the stubs, in which the designer can add details. The IDE can then usually ensure that everything stays in sync (UML(Code(Javadoc) as the project evolves. If the project requires the API docs to be in a separate document, there are several tools available to convert the Javadoc to PDF. Use commonly-available tools (Checkstyle, Eclipse) to verify that the code base is adequately documented by Javadoc.12. Automated Code Metrics and Quality Analysis: The project should regularly analyze the application code to gather metrics and check for compliance to industry and project-specific coding standards. For example, metrics can identify excessively long methods, methods without Javadoc, tightly-coupled dependencies, dead code, and other areas for improvement. The metrics will help gauge how well the other best practices are being followed. The AET-approved tool is Borland Together Architect [9]; however, note that many open source tools are also excellent: JavaNCSS, JDepend, PMD, FindBugs, QJ-Pro, and Checkstyle.13. Carefully Manage Data Migration: Data migration from existing sources to new sources/formats (a.k.a. transition strategies) is a major challenge, and should be treated as such. Do not underestimate data/hardware migration tasks or leave to junior programmers. This practice also considers how test data will be created and kept up-to-date.Process View best practices14. Identify Non-functional Requirements: Identify and document the non-functional requirements, particularly in the areas of performance expectations (number of transactions, screen response time, etc.), application availability, security, number of concurrent users, hardware and O/S requirements, logging, transaction management, exception handling, disaster recovery, and performance monitoring.

15. Consider Internationalization Requirements: I18N is a reality in most large enterprises and should be considered when architecting web applications. Sun has published a set of techniques that can be used when building JEE applications with I18N capabilities [8].

Development View best practices

16. Establish and Enforce Development Standards: From early on, establish a set of development standards that will be used by all developers on the team. Consider:

16.1. Exception-handling: A consistent exception-handling mechanism should be followed throughout the application. There are many resources on Java exception-handling best practices and antipatterns. In general, avoid complicated application-specific structures that depend on checked exceptionsit is often much more straightforward to wrap unrecoverable exceptions inside a RuntimeException and handle at the top-most level of the application. Exception handling and Logging (16.2) are inter-related; at minimum, exceptions should be effectively logged so they can be investigated later. RCF [15] provides an exception-handling framework and guidance.16.2. Logging: Logging should be done via a standard framework (e.g., Apache Log4J, Apache Commons, Java logging API, RCF) throughout the application. The logging framework should allow for various levels of logging (debug, informational, warning, error) and allow for re-configuration of the storage details (format, location, size, rollover, etc.). For enterprise-size applications, logging should utilize a set of specialized, independently-configurable loggers with distinct categories (security, performance, business function 1, etc.). Enterprise-class applications must also consider data sensivity, log file management, and clustering when designing a logging approach. RCF [15] provides training materials with additional logging guidance.

16.3. Common IDE: The project team should use the same Integrated Development Environment (IDE) tool, with identical configurations for things like code formatting, 3rd party plug-ins, etc. The choice of IDE should be made after carefully considering many factors; although the current ADE [9] recommends Oracle JDeveloper, a different IDE may provide the team with better productivity and quality (consider features like wizards, debugging, drag-and-drop tools, SCM plug-ins, testing and deployment on the chosen application server). Any other tools that the project team uses should be treated similarly. Recommendations for IDE set-up and usage are available for Oracle JDeveloper [10] and Eclipse [11].16.4. Coding Standards: Publish and enforce project-specific coding standards. The Global Java Forum recommends utilizing the RCF Java coding standards [10], which can be enforced with Checkstyle. The architect needs to provide specific direction from the beginning of the project as to the acceptable use of vendor-supplied and other 3rd-party components. Balance the productivity and quality gains of using vendor-supplied components vs. the decrease in portability and compliance to neutral standards. Various Java coding standards are available through the Global Java Community site on knowledgeCentre [12].16.5. Peer Reviews: Peer reviews have long been shown to have value by identifying and removing defects before they are released to the testing or (worse) production environment. Any artifact from the development process should be reviewed, including plans, requirements, architecture, design, code, and test cases. However, the team should ensure peer reviews are effective [13] and not overly bureaucratic.16.6. Configuration Management Standards (see best practices below)16.7. Testing Standards (see best practices below)17. Configuration Management (CM) Best Practices17.1. CM Tool: Utilize a configuration management tool and associated build scripts (Ant) to manage the project development. Everything that can be changed, and affect the behavior of the application, is a candidate for configuration control: source code, data, database structure, configuration files, test files, etc.). Ensure at least one person on the team is an expert in using the CM tool to manage labels, branches, and builds. The developers should also be familiar with source control features in their IDE to compare code, rollback, merge, etc. Further guidance on Borland StarTeam, the EDS-recommended CM tool for Java, is available on the AET website [14].17.2. Automated Builds: The project should utilize an automated environment to build the application and manage dependencies. Consider using de facto standard tools such as Ant, Maven, and CruiseControl. A huge advantage of automating the build process is that many of the other best practices (Automate Unit Testing (18.1), Code Metrics (12), etc.) can be automated by attaching them to the build process.17.3. Continuous Integration: Code under development should be integrated and built at regular intervals (preference towards nightly builds) in order to catch problems early. This practice is particularly important with distributed teams, where merge problems can arise if code is checked-out for long periods of time or code is being developed in a tag team type of approach (i.e., follow the sun). Continuous Integration is most effective when combined with Automated Builds (17.2), Automated Unit Testing (18.1), and Automated Code Metrics and Quality Analysis (12). Keep an eye on the forthcoming Gauntlet tool from Borland.17.4. Build Management: The project should develop a holistic view of the build process, encompassing everything from source management and compilation all the way through to release to the customer. If the development team is distributed, ensure adequate documentation, communication, and controls are in-place to manage the entire lifecycle (develop, integrate, test, deploy). Ensure all developers are aware of and trained in the lifecycle processes that have been established for the project.

18. Testing Best Practices18.1. Automated Unit Testing: Unit tests should be created using JUnit or TestNG. Strive for at least 75% code coverage (which can be measured with Optimizeit or jcoverage tools). If a strong unit test suite is not already in place, consider using commercially-available tools to assist developing an initial set. A wealth of usage guidance is available for JUnit, including the RCF [15] training materials.18.2. Reusable Test Plans: Integration and functional tests should be created with reusability in mind. There should be a common library and index of test plans for the application. If possible, automate tests using Mercury WinRunner, HttpUnit, Fit, Canoo Webtest or similar tool.

18.3. Automated Regression Testing: Existing test scripts should be executed before each release to ensure existing functionality continues to work as expected.

18.4. Performance Testing: Conduct performance/load testing and profiling at regular intervals, using tools like Borland Optimizeit [14] and JMeter.

18.5. Model Office Test Environment: A test environment that mirrors the production environment as closely as possible (hardware, middleware, etc.) should be established and used to perform a variety of tests (particularly performance tests) prior to production deployment.

18.6. Test-Driven Development: Test-driven development (TDD), in which automated (JUnit) tests are written simultaneously with the low-level design and coding tasks, is now widely considered a best practice [23]. It tends to yield simpler, cleaner designs that have fewer bugs while simultaneously creating Automated Unit Tests (18.1) along the way.

19. Object-friendly Database Design: The persistency approach, database and object models should be designed concurrently, by specialists familiar with JEE implementation. The Java architect and data architect must agree on the overall design and persistency approach, especially regarding usage of tools such as TopLink, Hibernate, or iBATIS.20. Manage Defects: As defects are uncovered in the project, they should be tracked in a database such as StarTeam, ClearQuest, Bugzilla, or Aldea. Ideally, the defect management tool should be integrated with the CM tool (if not, utilize a numbering scheme that can track how/when defects are corrected). Defect tracking allows the project management team and client gauge when a project is ready to release, as well as identify problems with the development process.

Physical View best practices21. Utilize Clustering: In cases where the number of clients will increase (or has increased since initial deployment), improve scalability, availability, fault tolerance, and performance by enabling clustering of application and database servers. This usually involves some vendor-specific tuning/optimization see Optimize Servers (23).22. Utilize Standards-based Re-usable Middleware, Components, and Frameworks: To the extent possible, the application architecture should take advantage of existing or acquired middleware, 3rd-party components, and frameworks based on Java standards vs. building its own. Consult the Technology Policy [21] before choosing any components outside of the standard Sun JEE distributionat this time, RCF [15], is the only Approved framework. However, many projects have had success with components/frameworks such as Xerces, Xalan, Struts, Spring, Hibernate, and Log4j. For further details on the advantages and disadvantages of many of these technologies, refer to the RCF Model Implementation Guide [16].23. Optimize the Server(s): Especially in greenfield deployments, the application and database server(s) must be tuned for optimum performance and reliability. This usually requires vendor-specific knowledge (e.g., BEA WebLogic vs. JBoss). Consider bringing in a vendor-certified consultant for a week or two.

24. Plan Deployment Early: Implementation plans, deployment scripts, support guides, etc. should be created early in the project, and continually updated and reviewed. Such an approach helps to ensure that compatibility, support, security, and a host of other potential issues are identified and addressed by the architecture. There are a variety of resources (checklists, etc.) available on this topic.25. Production Support Handbook: Every application should have some type of guidebook to assist support personnel with both common and abnormal support situations. Such a handbook is also useful for new developers, because it should describe the runtime characteristics of the application, such as: system environment, hardware/middleware, application schedules, configuration files, locations of databases, contacts, etc. Shells and completeness criteria can be found in the BPR [20].Architecture Antipatterns

The following bad practices should be avoidedif already present, consider institutionalizing one or more of the indicated best practice(s). When available, we have referenced the origin of the antipattern name; if not given, the name was invented by the authors.Architecture Antipattern / smellRefactored Best Practice(s)

Analysis Paralysis / Death by Planning: Striving for perfection and completeness in the analysis phase leads to project gridlock. Excessive preplanning and detailed dependency-driven schedules leads to postponement of development work and useless plans that must be constantly revised for even insignificant changes. [17]Iterative Methodology (1)

Architecture/Design by Implication: System developed with poorly-defined or undocumented architecture. Enhancement projects jump right into coding after gathering the requirements. This often occurs due to overconfidence based on recent success. [17]Technical Launch (2)

Experienced Architect (4)

Create UML Diagrams (8)

Production Support Handbook (25)

Big Ball of Mud [18]: Due to a variety of forces over time, the application design has eroded to the point that it is difficult to analyze and maintain. This is the application version of the giant hairball. It shows signs of other antipatterns such as spaghetti code and cut-and-paste programming.Automated Unit Testing (18.1)

Automated Code Metrics & Quality Analysis (12)

Refactoring

Black Box Development Process: The project manager and/or client do not have visibility into the development process, such as the status of builds, testing status, open defects, or overall code quality.Iterative Methodology (1)

Automated Code Metrics & Quality Analysis (12)

Establish and Enforce Development Standards (16)

Manage Defects (20)

Brittle Application: The application design is not fault tolerant, or does not gracefully deal with unexpected conditions. Behavior is inconsistent for different clients, times of the day, etc.Utilize Use Cases [consider failure conditions] (7)

Identify Non-functional Requirements (14)

Exception Handling (16.1)

Manage Defects (20)

Plan Deployment Early (24)

Database-Object Mismatch: The database design does not map cleanly to the class model, or vice-versa. This is not to say that there should be a one-to-one correspondence, but if classes routinely map to data stored in more than 1 or 2 tables, this is a sign of trouble. This often occurs when the DBA insists on a hyper-normalized database design that does not correspond to the class model. It can also occur when changes to one are made without consideration of impacts to the other.Create UML Diagrams (8)

Create E/R Diagrams (9)

Manage Data Migration (13)

Object-friendly Database Design (19)

Ethnocentric Web App: The web application does not adequately handle internationalization requirements such as different language error messages, local date or number formats, images, etc.Consider InternationalizationI18N Requirements (15)

Fire Drill / Death March: Development (coding and testing) only proceeds once all detailed requirements are captured and a complete paper architecture is created. This often results in long work weeks and frustration due to the application not working as originally designed. [17]Iterative Methodology (1)

Prototype (3)

Bake Best Practices Into the Project Plan (6)

Fox in the Hen House: Changes are put into production that are not adequately documented and/or tested. This often results in defects and maintenance problems over the long term. It is closely related to the Lack of Development Processes antipattern (oftentimes, documented engineering standards and processes exist, but they are not enforced, which is equally problematic). [19]Code Reviews (16.5)

Testing Standards (16.7)

Build Management (17.4)Manage Defects (20)

Integration Nightmare: Integrating code before each release is a cumbersome and error-prone task. CM tool specialists and tech leads must manually merge code and manage dependencies to ensure the code base is built correctly. Deployment to test and production servers is also manual and error-prone.Manage Data Migration (13)

Configuration Management Best Practices (17.x)

Manage Defects (20)


Lack of Development Processes: There are either no visible software development processes or those that exist are disjointed and informal. The developers on the project are each doing their own thing. It is difficult to integrate new developers into the project team. This antipattern also applies when a development process is documented, but not followed. This is the father of all other SCM antipatterns [19].Bake Best Practices Into the Project Plan (6)

Establish and Enforce Development Standards (16)

Manage Defects (20)


Goldplating (Over-Engineering): The application design is overly (unnecessarily) complex and lacks a common architectural vision. This is often caused by designs developed by groupthink (Design by Committee) or inexperienced designers (using inappropriate functional decomposition techniques). It can also be caused by experienced architects infatuated with new, cool technology that can solve tomorrows problems tomorrow rather than trying to solve todays business problems with todays technology. [17]Experienced Architect (4)

Test-Driven Development (18.6)

Refactoring

Paper-Driven Architecture: Application designs are captured using ill-suited tools, most notoriously Microsoft Word. Besides being extremely inefficient and inappropriate for OO projects, this approach often leads to outdated, error-prone documentation.Create UML Diagrams (8)

Create E/R Diagrams (9)

Utilize MDA Techniques (11)

Performance Headache: The application cannot adequately handle the number of concurrent users, transaction loads, etc.Prototype (3)

Identify Non-functional Requirements (14)

Performance Testing (18.4)

Utilize Clustering (21)

Server Optimization (23)


Reinventing the Wheel: Because of ignorance (whats log4j?), pride (were unique), or other forces (bureaucracy, thrift, politics), the application has coded many features from scratch rather than re-using available frameworks, components, middleware, etc. Such code is often sprinkled throughout the application due to cut-and-paste programming rather then development of reusable components. [17]Technical Launch (2)

Experienced Architect (4)

Utilize Standards-Based Re-Usable Components (22)

Testing Antipatterns: There are several testing antipatterns, the most common of which are Sure Thing (no testing), Great Expectations (lackadaisical testing), and test environment mis-match (test environment does not match production). [17]Bake Best Practices Into the Project Plan (6)

Testing Best Practices (18.x)

Manage Defects (20)

Tightly-Coupled Interfaces: Interfaces between applications and intra-application services are tightly-coupled, that is, that even small changes to implementation details requires changes to the client (for example, recompilation or re-formatting).Utilize a Service-Oriented Architecture (10)

Under-Engineering: The application is poorly designed, expensive and difficult to maintain. This situation often occurs when time is not taken to appropriately design or incorporate changes into the existing design. It usually betrays an ignorance or lack of attention to architecture.[all]

Unique Architecture: The architecture does not conform to standard models (for example, there is no obvious layering or conformance to generally-accepted MVC approaches), and is thus difficult to understand for new developers. There are cases where architectures break new ground (for example, the first application frameworks that utilized Dependency Injection or Aspect-Oriented Programming), but these should be rare. Technical Launch (2)

Conform to Standard Architecture Patterns (5)

Utilize Standards-Based Re-Usable Components (22)

Use Case Antipatterns: There are many antipatterns related to use cases. The most prevalent are to either not document requirements or to use an alternate format (e.g., Gigantic User Specs Document) that is not well-aligned to OO development. Other common use case antipatterns are: too much detail, inconsistent format, too many extensions/includes, equating use case diagrams with use case documents, too many user interface details, missing subjects/actors, and too many technical details.Bake Best Practices Into the Project Plan (6)

Utilize Use Cases (7) and best practices [6]Manage Defects (20)

References

We are indebted to a variety of and external industry experts for their contributions to this document. 1. Larman, Craig. Agile & Iterative Development: A Managers Guide. Addison-Wesley, 2004.

2. Sun Enterprise Java Blueprints: http://java.sun.com/reference/blueprints3. A3 Architecture: http://infocentre.eds.com/who/work/a3/index.html4. Portfolio Management (Applications TS&A) library: https://knowledgecentre. .com/sites/kc16/c4/default.aspx5. Delivery Systems Architecture (DSA) website http://infocentre. .com/sell/tools/dsa/index.html

6. OO and UML Best Practices a work-in-progress, pending approval by the Global Java Forum, will be catalogued on the Global Forum website [12]7. Cockburn, Alistair. Writing Effective Use Cases. Addison-Wesley, 2001.

8. J2EE Internationalization and Localization http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/i18n/i18n.html9. Application Development Environment (ADE) standard tools websitehttp://www.GAD QMS-am. .com/tools/Standard_Tools.htm

10. RCF JDeveloper Best Practices, https://knowledgecentre. .com/sites/kc99/Technical/Best%20Practices/JDeveloper/RCF%20-%20JDeveloper%20Best%20Practices.pdf

11. Eclipse & Together Architect Standard Set-up, http://portal.nz. .com/sites/AppDel/NZADU/javacoe/Shared%20Documents/Eclipse%20and%20Together%20Architect%202006%20Setup.doc

12. Global Java Community knowledgeCentre site: https://knowledgecentre. .com/sites/kc44/s2/default.aspx

13. Wiegers, Karl. Seven Deadly Sins of Software Reviews. http://www.processimpact.com/articles/revu_sins.html

14. AET Toolkit Borland Collateral website: http://www.GAD QMS-am. .com/tools/Borland_Collateral/Documentation.htm#AET_Best_Practices

15. Reusable Component Framework (RCF), https://knowledgecentre. .com/sites/kc99/default.aspx

16. RCF Model Implementation Guide, https://knowledgecentre. .com/sites/kc99/Technical/Best%20Practices/RCF%20Model%20Implementation%20Guide.PDF

17. Brown, Malveau, McCormick, Mowbray. Antipatterns. Wiley, 1998.

18. Foote and Yoder. Big Ball of Mud. http://www.laputan.org/mud/19. Brown, McCormick, Thomas. Antipatterns and Patterns in Software Configuration Management. Wiley, 1999.20. Best Practices Repository (BPR) http://www.GAD QMSbp-am. .com/GAD QMSComm/libraryhome.asp

21. Technology Policy http://techpolicy.iweb. .com/22. New Zealand Java CoE Shared Documents: http://portal.nz. .com/sites/AppDel/NZADU/javacoe/Shared%20Documents/Forms/AllItems.aspx23. Test-Driven Development website: http://www.testdriven.com Template Control: MS Word Portrait TemplateTemplate Version 1.2 -- Approval Date 20 January, 2006

Saved 12 May, 2015

Page 1 of 14GJF_Architecture_Best_Practices_2.00.docSaved 12 May, 2015

Page 14 of 14

GJF_Architecture_Best_Practices_2.00.doc