Indiana University J2EE Development Standards
University Information Systems September 2004 Version 1.4
Table of Contents
Introduction...... 3 Methodology...... 6 Architecture...... 12 Coding Conventions...... 18 Standard Libraries ...... 20 Tools ...... 21 Development Platform ...... 22 Shared Services ...... 23 Deployment...... 24 References and Links...... 26 Appendices...... 28
J2EE Development Standards v1.4 - 2 - J2EE Development Standards: Introduction
Why have we developed this J2EE Development Standards document?
Most developers are aware of the benefits of development standards as they relate to long term maintenance costs. 80% of the lifetime cost of a piece of software goes to maintenance. Often times, the original author of the code does not perform the maintenance. So, it stands to reason that, over the long haul, applying standard development practices across an organization will result in substantial maintenance savings. In addition, good standards promote better quality applications, code reuse, and may enhance portability.
In addition to this fairly common definition of why we have standards, this document serves another purpose. It is hoped that this document will provide simple and concise instructions that may actually make it easier to develop applications in UIS. In order for standards and guidelines to achieve these stated goals, developers must adhere to them. To encourage them, the standards and guidelines must be easy to follow and relatively flexible.
Finally, project plans must accommodate compliance. Avoiding standards due to project deadlines is not a valid excuse. Complying with standards should be built into work plans. UIS management must support compliance. The “quick path” solution today will cost us dearly in maintenance over the life of our applications. A standards-based approach gives us more time over the long run to work on new services.
Whether you are a brand new developer in UIS or a seasoned programmer, we hope that you find this document easy to follow and helpful. If you do not find it helpful or if you have suggestions for improvements, please contact the Systems Integration Team. Our goal is to help UIS development teams do their jobs more effectively and efficiently.
What is a “Standard”?
For the purposes of this document, a “standard” is a development practice that is deemed most important to ensure that we do not compromise on our collective and fundamental development principles. Therefore, “standards” outlined in this document should be strictly adhered to by all J2EE developers in UIS. With each exception, we lose on the maintenance side. So, it is expected that all UIS J2EE developers will adhere to these standards.
If a particular standard is preventing us from making progress on our deliverables, what are our options?
J2EE Development Standards v1.4 - 3 -
It is never the intent for the standards to prevent work from getting done. The intent is for the standards to provide more help than hindrance to the development process. If a situation should arise where an application team feels it must deviate from a standard, the first step is to communicate with the Systems Integration Team. It could be that via email discussion or a short meeting, we can collectively arrive at a recommended approach. In some cases, we may find a way to solve the problem and still adhere to standards. In other situations, we may need to make an exemption to a particular standard. Either way, if the petitioning application team and SIT are in agreement on the recommended approach, the problem is resolved. (Note: Depending on the frequency of a given issue, the application area may move to make a permanent change to the standards document. This process is described in the next section).
If for some reason the application team and SIT cannot arrive at a means of complying with a standard, the Director or the Director’s designee for the petitioning application area will be provided information describing the alternatives and the pros and cons of each. The Director or their designee will then resolve the issue in a timely manner, to allow development to proceed. The application team should then bring up the issue at the next meeting of the J2EE Standards Committee to accommodate future instances. (See discussion of Committee below.) Teams should be aware that deviations from standards may adversely affect the level of support other UIS teams, including SIT, will be able to provide a given application.
How can a standard be changed? What if a standard is not “helpful”?
In addition to the goals for minimizing long term maintenance costs of UIS applications, this document is also intended to help UIS developers do their job. If for some reason a particular standard is problematic or unhelpful to this process, there must be a way change it. UIS is still very new to J2EE development and we continue to learn new things every day. Therefore, this standards document must be a living, evolving document. It is not recommended that it be printed off and put on a shelf for years. Rather, the latest and greatest version of the document should be checked out frequently to be sure that even the most recent changes are reflected. SIT will publish “Release Notes” with each new version of the document making it easy to identify the latest changes.
If a particular standard is not helpful or is frequently causing problems, a proposal to change the standard can be brought forth by any UIS application team, infrastructure team, or SIT. These changes to standards can be discussed in one of two venues. First, if it is an urgent topic, it can be addressed at the next meeting of the developers’ “Java Hour”. In addition, a J2EE Standards meeting will be scheduled once a quarter to discuss proposed changes to this document. Either venue is an appropriate meeting to discuss changes to the standard.
J2EE Development Standards v1.4 - 4 - A “J2EE Standards Committee” will be established to determine and regulate J2EE standards for UIS. This committee will be made up of people appointed by their managers representing application development teams across all of UIS. Every UIS development team will be represented.
Regular attendance by J2EE Standards Committee members will be required. The time commitment is relatively small. Eighty percent (80%) of the members of the Committee must be present to conduct business. Any proposed change to the written standards must be approved by eighty percent (80%) of the members present.
The meetings will be scheduled on a quarterly basis. Meetings will take place only when there are agenda topics or standards modifications up for discussion. Emergency meetings may be scheduled when decisions need to be made quickly.
Who “owns” these standards?
Every J2EE developer in UIS owns these standards. It is the developers that must maintain UIS code over the long term. It is the developer who is accountable for their code and productivity. Therefore, the developers are the rightful owners of these standards. SIT does not own the standards nor will SIT implement any sort of formal enforcement process. UIS members may point out potential deviations from standards and make a point to communicate their concerns, but that is as far as it will go. It is up to each developer in UIS to actively participate in this process, encourage and train new developers to adhere to the standard, and to make the standards helpful to meeting the overall goals and objectives of UIS.
J2EE Development Standards v1.4 - 5 - J2EE Development Standards: Methodology
A methodology for software development should establish procedures and techniques that developers can rely on to promote quality software and services. Adopting a methodology means following a prescription of methods that the developer community has judged to be useful, coherent, and worthwhile.
What is the value of a Methodology?
When we follow an established software methodology, we gain from the experiences of others in developing software that satisfies user requirements. We can take advantage of proven best practices, and avoid the pitfalls that have crippled or scuttled other projects. An effective methodology must consist of methods that work, and work consistently across a wide range of requirements.
Most application projects involve a number of analysts and developers. Coordinating their efforts is crucial to the success of a project. A methodology focuses and integrates the efforts of each individual in these teams, and refocuses them throughout its tenure.
In addition, when we follow a methodology, we also document the process for those who will use or support the product. Developers and end users ideally commit to a set of shared goals, and to a common understanding of what they mean. If there are disagreements on the product, we can trace our intentions through the process and identify corrections for the next iteration.
Software products are now expressed as Web services, and in turn are integrated with other Web services. The organization and control that an effective methodology brings to developing in this complex environment are crucial.
The Unified Modeling Language
The System Integration Team (SIT) uses methods from the Unified Modeling Language (UML) and recommends that UIS developers do so. UML is an industry standard of the Object Management Group (OMG) for “specifying, visualizing, constructing, and documenting the artifacts of software systems.” It defines twelve types of diagrams in three categories: Structural, Behavior, and Model Management. Any or all of these tools may be employed in defining and refining the system’s requirements, functions, and behaviors. SIT recommends completing Use Cases, Class Diagrams, and Sequence Diagrams as a minimum.
J2EE Development Standards v1.4 - 6 - UML originated at Rational Software, a software technology company that offered it to the OMG for independent standardization. Rational in turn developed its Rational Unified Process (RUP), “a guide for how to effectively use the Unified Modeling Language”. While the cost of RUP as a commercial product currently precludes its use at UIS, SIT heartily endorses its stated Best Practices:
1. Develop software iteratively 2. Manage requirements 3. Use component-based architectures 4. Visually model software 5. Verify software quality 6. Control changes to software
The Development Cycle
“Develop software iteratively” directly addresses a growing understanding: the development process should consist of deliberately short iterations, with incremental improvements, and continuous evaluation. No significant product is born complete and flawless. We should adopt an “improvement spiral” as the development paradigm.
“Use component-based architectures” speaks to another contemporary reality: developers are now integrators of smaller-scale Web services. Systems are no longer autonomous or monolithic. UIS software products operate in the Web, and they are leaner and easier to use for it.
In total, these practices translate into a Development Cycle composed of the following key steps, each with its own methods and outcomes [www.indiana.edu/~sit/powerpoints/ UML Training for Designers Slides.ppt]. The term “cycle” reminds us that this process repeats, that it is a feedback loop, and that the outcome of each step feeds directly into the next. Early iterations through the cycle should focus on the initial three steps, while later iterations may be weighted towards the final steps.
Step 1. Requirements
Developers and end users must work together to gather requirements for the product. Developers alone cannot capture and portray all of the complexity of contemporary systems; the process must be cooperative. The dialog among end users and developers often identifies specific requirements that neither group would realize otherwise.
We start by developing a statement of the project mission, explaining the purpose and function of the project, including the context in which it will operate. This statement should be general but concise, explaining the business requirements addressed by the software product.
J2EE Development Standards v1.4 - 7 -
Next, we identify the set of Actors, listing them by role and a brief description of their interest in the product.
Given the Actors, we develop a prioritized list of Use Cases to describe the performance of the product in addressing the business requirements. We write a separate Use Case for each of the work functions that the product addresses.
The organization of a Use Case is well documented [www.usecases.org]. Its primary goal is to capture the functional interaction of the Actors and the System that serves the product, without regard to implementation. It should be developed iteratively in active dialogs between developers and end users, and should conclude in their mutual approval.
The Use Case becomes the contract between the developers and the end users. It should be completed and approved before proceeding further. If the product diverges from its intent, the Development Cycle should bring it back in line.
Step 2. Analysis
UML prescribes several diagrammatic tools that support the Analysis phase. SIT recommends Class Diagrams as a minimum. Starting with the Use Cases from the Requirements step, we identify candidate classes in Class Diagrams, including their attributes, methods, and relationships to other classes. We should use clear and concise labels to identify each.
These diagrams become the core documentation for the objects that deliver the product. They characterize the principal players in the project and how they do their work. They should evolve over time as they converge on satisfying the user requirements.
Step 3. Design
The Class Diagrams from the Analysis phase document the class attributes and methods. From these we create UML Sequence Diagrams to define the behaviors of the product. Sequence Diagrams portray the sequence of events, the messages between classes, and the business data involved in these events, among the various classes.
Sequence Diagrams can suggest the appropriate distribution of functions among classes. They can help approach the mutual design goals of “low coupling, high cohesion”, i.e., minimum dependence among objects and maximum integration of methods within an object. Developers can quickly see the flow of a process in a Sequence Diagram, and pin down overly convoluted flows as well.
J2EE Development Standards v1.4 - 8 - We can also identify appropriate patterns in the Design phase. For example, we can consider Struts, JRelational, and/or UIS Utilities as good fits for the project. Also, a preliminary concept of the user interface should be available by now, and it suggests Form and Action objects.
Step 4. Implementation
The set of Sequence Diagrams developed in the Design step is the starting point for implementing Java classes and their methods in code. The integrity of these diagrams and the code should be maintained; if design changes are made during coding, we should make reasonable efforts to refactor them back into the diagrams, at least in the Evaluation step.
Log4J logging should be included as classes are built. Integral logging statements make unit testing easier and more effective.
Developers should comply with the current coding conventions, as described in the Coding Conventions section. Conforming to these conventions improves the readability and maintainability of code for both current team members and future support groups.
Development teams should conduct code reviews at the completion of major modules. These reviews both improve the quality of code and familiarize team members with the coding techniques and design approaches used.
Step 5. Test
Tests should be written as modules are developed, from the start. New modules should be Unit Tested during and after implementation. Together with existing modules, they should be Regression Tested collectively in JUnit test suites on a regular schedule. The results of these tests should be passed on for evaluation and correction as needed.
Step 6. Deployment
Modules should next be deployed for users to evaluate. This step is not intended for production use.
Step 7. Evaluation & Planning
Finally, we should evaluate test results and feed appropriate changes back into the development cycle. While working in the cycle, teams avoid “quick fixes” in favor of keeping the design and analysis products current.
J2EE Development Standards v1.4 - 9 -
End users should be engaged in the evaluation and actively compare results with requirements. They should signoff on favorable comparisons, and ensure that appropriate changes are fed back into the development cycle.
When shortcomings are identified, developers and end users must plan how to direct changes back into the original steps. These improvements then feed the next development cycle.
Version Control:
Modules should be maintained in the version control system that SIT prescribes in “UIS CVS Release Standards”.
SIT supports WinCVS, in conjunction with the integral CVS support in the J2EE IDE, for version control of J2EE development. As a “concurrent” versioning system, it supports concurrent file access from multiple users. WinCVS provides facilities to create “tags” to identify significant versions, and “branches” to denote release versions. Branch names should end in “_br”, and may include either the date in the form yyyy_mm_dd or the release number in the form i.j.k, where
i = number of major release: significant new features or design changes j = number of minor release: minor enhancements and cumulative fixes k = number of patch release: fixes only
Developers may modify a specific release in a local copy using WinCVS and the IDE.
Release Management:
Release of J2EE components should follow the SIT recommendations in “IU J2EE Release Preparation”.
These recommendations include the following responsibilities for developers:
1. “Creation of common structures on developers’ workstations”
“IU Resource Bundle Structure” c:/opt/
2. No passwords in code or in the version control system
3. Security and Property settings files packaged for initial deployment
J2EE Development Standards v1.4 - 10 - 4. HTTPServer files packaged properly
5. Application Server files packaged properly
6. DDL and XML files stored in project
7. Deployment files sent to ESA
Drop boxes will be provided for Test and Production files
ITSO/ITPO notified on move to Production
J2EE Development Standards v1.4 - 11 - J2EE Development Standards: Architecture
The software architecture that a development team adopts establishes the basic form and structure in which an application is developed. It gives developers some standard constructs for organizing the development, rather than forcing them to start with a clean sheet. Teams adopt Methodologies as the conceptual tools for developing applications. The Architecture then is the set of plans and “building codes” for its construction. It includes Design Patterns and Frameworks as ground rules for organizing component and application design.
The Architecture of Distributed Applications
The contemporary architecture of applications is a set distributed components that provide distinct business services. The principal delivery of these services is to users via the Web. For UIS applications, the primary delivery mechanism is the OneStart portal. The application design supports distribution, while its deployment may or may not be distributed.
SIT recommends designing the components that comprise an application into three tiers: Presentation, Business, and Data. The assignment of Java classes to these tiers should be made in the UML Design step.
The Presentation tier focuses on the presentation of the data to the user in the context of the user interface, e.g., the Web browser. SIT currently recommends the Struts framework for organizing Java ServerPages (JSPs) and Java Servlets to present user data.
The Business tier provides the enterprise logic. It includes the components that capture the business rules of the enterprise. The Business tier should also include one or more boundary classes to direct access to the Data tier. It may support multiple Presentation tiers.
The Data tier is the data repository for the application. It provides the data storage, retrieval, and maintenance. SIT recommends employing Data Access Objects (DAOs) to encapsulate the data sources, and using the jRelational framework to isolate access to the database.
Design Goals
Goals for software design help keep teams on track during development. They may be the deciding factor in a design decision. Since there are usually many ways to satisfy the same requirement, considering goals can move the design in a preferable direction, or away from an undesirable one. While a module may succeed at fulfilling its enterprise
J2EE Development Standards v1.4 - 12 - function, it may fail in approaching goals that will also make it easier to understand, to maintain, and to change.
SIT recommends that developers consciously work toward the following goals:
1. Simplicity – preference for simple and straightforward design, in a healthy balance with (and even over) performance issues. Satisfy the business requirements before optimizing for performance.
2. Readability – writing code which is readable, structured to be readily understood, appropriately commented, and free of obscure or self-serving hacks.
3. Maintainability – organizing code and associated files with concern for their maintenance and support by others not familiar with the development
4. Data encapsulation – one of the tenets of object-oriented programming that ensures only regulated access to object data
5. Refactoring – renaming and reorganizing coding components (e.g., methods, variables, classes) throughout development to simplify their structure without modifying their function. Refactoring eliminates redundancies and unused functionality. It rejuvenates the design, saves time, and increases software quality.
Patterns
A pattern is a codified, repeatable solution to a common problem. Design patterns have been identified as software developers realized that a technique has a history of satisfying some requirement, overcoming some obstacle, or delivering some result. Following a pattern often helps developers avoid pitfalls that may not be obvious in the initial development steps, and makes application support both easier and more effective.
Developers should strive to understand patterns, and then use them. SIT recommends that developers become familiar with the following pattern sets:
1. General Responsibility Assignment Software Patterns (GRASP) – set of nine widely used design patterns
2. Sun Java Center Core J2EE Patterns – set of J2EE-based solutions gathered over three years at Sun Java Center
3. “Gang of Four” Patterns – pattern set named after authors of classic text, “Design Patterns: Elements of Reusable Object-Oriented Software”
J2EE Development Standards v1.4 - 13 -
Frameworks
Development organizations have also formalized frameworks to aid software development. Frameworks simplify a software solution, generally by abstracting out process details into a more functional view. A framework is central to the design of an application when it is adopted, while a library is simply shared code that is included in a project.
SIT recommends that applications use the following frameworks:
1. Struts – organizes Java components to present user data in the Web context. Addresses the View portion of the MVC pattern.
2. jRelational (JRF) – abstracts SQL database code and isolates it from business logic. Applications should use only up to Version 1.7. JRF is superseded in new projects by OJB.
3. ObjectRelationalBridge (OJB) – abstracts SQL database code and isolates it from business logic. Addresses the Data portion of the MVC pattern. OJB does its own connection pooling with the Jakarta Commons in the UIS Java Libraries.
4. JUnit – implements Unit Testing for individual class modules and suites of modules
5. Log4J – multi-tiered logging
Configuration managers should be familiar with these frameworks, and teams should complete related training or consult with SIT when planning to incorporate them in their project design.
Java Virtual Machine
The Java Virtual Machine (JVM) is the “platform-independent abstract computing machine and execution environment” that delivers uniform presentation and interaction on a variety of user nodes. Along with Java API libraries and developer and administrative tools, it is part of the Java Development Kit (JDK) offered by vendors that participate in the J2EE development market.
SIT recommends that teams use the same JDK vendor and version in the J2EE IDE that they plan to deploy in production.
Databases
J2EE Development Standards v1.4 - 14 -
UIS applications developed in J2EE rely on Oracle databases for data storage. SIT requests that the DBA Teams collectively maintain a list of servers for database services related to development, test, and translation, including any plans for future server deployment.
Database connections have the potential to become major performance bottlenecks as Web services scale to large numbers of users. A reliable mechanism for allocating and managing data sources and caching queries is critical for every application.
Developers should specify parameters for pooling database connections in resource files, examples of which are included in the “Developer Responsibilities” section of the “IU J2EE Password and Resource File How To” document. In particular, properties files under the security and settings directories must be created, to configure the database connection pooling without recoding.
The Oracle Client software can be downloaded from IUware. The Client install is useful if the developer would like to use SQL plus or uses a tool that requires an Oracle Client installation.
SIT recommends that our J2EE applications be developed using the Type 4 Java implementation of the Oracle Client. The Type 4 implementation is fully Java-based and requires only that the Oracle class libraries be installed, as provided in the UIS Java Library. Use the following connection URL:
jdbc:oracle:thin:@(description=(address=(host=es01.uits.indiana.edu) (protocol=tcp)(port=1521))(connect_data=(sid=GEN2DEV)(SERVER=dedicated)))
Developers must ensure that database transactions are handled appropriately. Consult the “Transaction Management” sections in the Appendices for an examples of managing transactions in the recommended framework.
Database connections should be managed properly by the participating application. SIT recommends that the application close its connections in a finally block, or otherwise document where closures are expected, after it is finished accessing the database.
Directories
J2EE applications must require that their users are authorized to guarantee appropriate access. SIT recommends the Active Directory Service (ADS) domain for general- purpose application authorization, and the IU Global Directory Service (GDS) for user information. Both of these directories use the Lightweight Directory Access Protocol (LDAP). SIT provides the UIS Utilities library with code to access either of these services.
J2EE Development Standards v1.4 - 15 -
Data Exchange and Messaging
The Extensible Markup Language (XML) has become the lingua franca for data exchange among distributed applications, and for structured data in general on the Web. SIT recommends that developers consider XML to maintain and communicate document content, and use XML technology throughout the design.
Simple Object Access Protocol (SOAP) is an XML-compliant protocol for representating remote procedure calls and responses. It is currently a submission to the World Wide Web Consortium (W3C). Developers should consult with SIT before considering SOAP for UIS applications.
The Java Messaging Service (JMS) API provides asynchronous messaging among J2EE components, expressed as message-driven Enterprise JavaBeans. Developers should consult with SIT before considering JMS for UIS applications. SIT is currently exploring a JMS solution.
Enterprise JavaBeans Technology (EJB) is a J2EE component model for distributed business applications. It provides for many business services, including security, resource pooling, and transactions. Developers should consult with SIT before considering EJBs for UIS applications.
Security
UIS applications must ensure that their user requests are both genuine (authentication) and appropriate (authorization). Only when user identity and user privilege are both verified should access be granted.
UIS applications should employ the Central Authentication Service (CAS) to authenticate users in a single sign-on. Applications must then do their own authorization.
All secure Internet communications involving UIS applications should use the Java Secure Socket Extension (JSSE). JSSE is Sun’s Java implementation of the Secure Sockets Layer (SSL). SSL is an industry standard protocol that runs between TCP/IP and higher-level application protocols, such as HTTP and LDAP. It uses public-key cryptography to verify client and server identities. SIT will provide SSL certificates, issued in turn by a Certificate Authority (CA). SIT maintains installation instructions at “How to add a trusted certificate”.
Logging
J2EE Development Standards v1.4 - 16 - Developers should incorporate logging into the design and coding of all J2EE applications. SIT recommends Log4J to provide multiple levels of logging: debug, info, warn, error, and fatal. Each logging level may be triggered and directed independently in a configuration file. Specific logging functions may therefore be changed without code changes or redeployment.
Log4J requires the following declaration in the participating class:
private static final org.apache.log4j.Logger LOG = org.apache.log4j.Logger.getLogger(className.class);
Logging messages may then be inserted for any of the five levels:
LOG.debug(messageString); LOG.info(messageString); LOG.warn(messageString); LOG.error(messageString); LOG.fatal(messageString);
UIS applications must implement two logging standards before the start of testing:
1. debug-level logging at entry and exit of each substantial business method 2. exception catch blocks should implement either debug- or error-level logging, depending on the severity of the exception
As a best practice, debug-level logging should be added at the start of a branch.
SIT also recommends that the following rules be observed:
1. No use of printStackTrace() 2. No print to stdout or stderr 3. No password or identification should be included in a logging message
J2EE Development Standards v1.4 - 17 - J2EE Development Standards: Coding Conventions
J2EE development efforts involve the production of Java source code files, written and maintained by team members with varied backgrounds and preferences. While identical format and appearance in these files is unrealistic in any team of several individuals, teams can look to coding conventions to build common stylistic elements among their files. Rather than inciting holy wars, the dialog about conventions can identify common goals among team members, and recognize their individuality at the same time.
The Benefits of Coding Conventions
Sharing, testing, and maintaining Java files are integral parts of an application’s lifecycle. A familiar appearance to its code simply makes these jobs easier. Sun Microsystems, the steward of Java and J2EE, cites readability and ease of maintenance as the primary benefits of adhering to coding standards. Readable code can be debugged faster, its logic can be discerned more accurately, and changes can be integrated more coherently. Team members are more likely to share code if they can readily understand it. And team members, or future members, often maintain code that they did not author.
As such, it is more important to embrace some conventions than specific conventions. Following consistent conventions for coding style among team members promotes all of these benefits. On the other hand, the collision of wildly different styles will be an obstacle to the team’s progress.
References for Coding Conventions
SIT endorses “The Elements of Java Style” (Allan Vermeulen et al; Cambridge University Press, 2000; ISBN 0-521-77768-2) as a practical and comprehensive set of recommendations for coding style. Teams may use the text as a starting point for building conventions that team members can employ. It can also be used as a checklist for issues that might otherwise be missed. Again, the conventions recommended in this book should serve as guidelines for teams to build consensus.
Sun Microsystems maintains the “Code Conventions for the Java Programming Language” site as a concise statement of style recommendations.
Some Specific Recommendations for Syntax
J2EE Development Standards v1.4 - 18 - The Java language standards prescribe lowercase package names. In addition, UIS projects should use the root qualifier of edu.iu.uis.appcode. to reference packages developed within UIS, where appcode is an application-specific code string.
SIT requires that source code files use spaces instead of leading tabs, which may not be handled uniformly among development tools.
Java includes the familiar conditional blocks if/else, while, do/while, for, and switch/case. SIT recommends that developers follow the syntax discussed in “The Elements of Java Style” text. Developers should also strive for simple and concise condition clauses and straightforward execution statements, and should code conditional statements to positive / true where practical. While conditional blocks with a single executable line should still be embedded in braces, the frequently inserted “if (debug) log” on one line is acceptable.
Comments
Adequate documentation in source code files includes Javadoc comments. Comments should explain the intended function of the subsequent code and why it is present, as much as how it accomplishes its mission. Of course, any subtle or necessarily complex code should be explained in comments, if only to acknowledge what considerations led to it.
The value of Javadocs in generating HTML-formatted documentation is apparent as distributed computing and shared code become more common,. Comment blocks for each method are delimited for Javadocs with “/**” and “*/”, and include @-prefixed strings to identify method parameters, return types, and exceptions. SIT requires these comment blocks for all public methods, attributes, and constants, and recommends their use for all private methods as a best practice.
If comments cover many lines, then developers should consider the likelihood that the code would benefit from refactoring.
Error Handling
Java provides comprehensive error handling as an integral part of the language. SIT strongly recommendes full implementation of the try/catch/finally construct to handle error conditions: • try blocks should wrap code that may potentially generate known exceptions. • catch blocks should include Log4J logging statements, and throws statements to throw exceptions up to calling methods as appropriate. • finally blocks should be included to release resources.
J2EE Development Standards v1.4 - 19 - J2EE Development Standards: Standard Libraries
SIT encourages using the UIS Java Libraries in all UIS J2EE development projects.
The Advantages of Standard Libraries
The UIS Java Standard Libraries are a uniform set of libraries for all UIS development teams. Using standard libraries provides several significant advantages:
• Employs common tools for the same functionality among applications • Reduces duplication of effort • Reduces errors with tested and supported code • Improves maintainability by using familiar solutions • Provides documented access to recommended frameworks
The Standard Libraries provide the API to several frameworks and toolsets recommended in the Architecture section. In particular, the Libraries currently support the following frameworks and tools:
• Struts and Struts Layout - presentation • OJB – object/relational mapping • JUnit – unit testing • Oracle - data resource management • Data Sources – JBoss or Tomcat supported • XML processing – use JDK 1.4
Some of these entries are maintained to support legacy applications.
Installing Standard Libraries
SIT maintains the UIS Java Libraries in the CVS version control system.
Versions
The version of the Standard Libraries used in developing applications should be set by the Configuration Manager for the development team. The Manager should also direct any appropriate version change for the entire team.
The current version of the Libraries should be the starting point for the team. SIT recommends that teams start a new project with the version currently in CVS.
J2EE Development Standards v1.4 - 20 - J2EE Development Standards: Tools
SIT maintains a list of development tools that it recommends to all UIS J2EE development teams. Each tool selection is endorsed and supported by SIT for the J2EE development environment. The SIT “Installing J2EE Products” site includes download links and installation instructions for some of these tools.
There is also a “UIS Developer Page” in the OneStart portal. If it is not one of your OneStart pages, or you have other questions about J2EE installations, please contact the Systems Integration Team.
SIT currently recommends the following tools for J2EE development:
Java Integrated Development Environment (IDE) Eclipse MyEclipse plugin
Application Server JBoss Apache Tomcat
Web Server Apache
Connector ModJK
JDK / SDK Sun JDK 1.4
Version Control WinCVS and Eclipse provided
Database Client Oracle – Type 4 JDBC Thin Client
UML Analysis and Design No Magic MagicDraw
Performance Monitor JMeter
Data Objects Generator
J2EE Development Standards v1.4 - 21 - OJB Eclipse plugin Build Data Objects (BDO) - old
Application Build and Deployment Ant
J2EE Development Standards v1.4 - 22 - J2EE Development Standards: Development Platform
SIT currently supports Microsoft Windows XP Professional and Microsoft Windows 2000 Professional on industry-standard PC desktops for J2EE development. If development teams select another operating system for development, they must provide their own support.
SIT also maintains a Website “Installing J2EE Products” of instructions and installation links for recommended Tools on Windows 2000.
J2EE Development Standards v1.4 - 23 - J2EE Development Standards: Shared Services
UIS Shared Services
The J2EE development platform gives UIS the capability to create shared services that may be accessed from UIS applications or other UIS shared services. They capture and encapsulate enterprise business logic for network access.
Shared Services developed by UIS must interoperate in the current and planned distributed computing environment. Their integration into this environment is the responsibility of their development team. SIT requests that the API for a shared service be documented with Javadoc, including its version, and published on an appropriate UIS site.
Accessing Shared Services
Part of the integration of a shared service into the distributed environment is managing its versions over its lifecycle. The development team should maintain and clearly identify each version. SIT requests that the API for a shared service include a method to return the versions it currently supports.
Support for Shared Services
The development team must assume the responsibility for supporting a shared service. The team should be organized to field support requests referred to it by the UITS Support Centers. SIT recommends that earlier versions of a service be supported for a minimum of six months. The version history should be documented on the appropriate site.
J2EE Development Standards v1.4 - 24 - J2EE Development Standards: Deployment
Release Preparation
SIT has outlined steps in the IU J2EE Release Preparation site to prepare for releasing an application into production. It includes a checklist of responsiblities for:
• the development team • the Enterprise Systems Administration (ESA) group • the Database Administration (DBA) group • the IT Security Office and IT Policy Office (ITSO/ITPO)
Further instructions are provided for passwords and properties files, for packaging to the application server, and for versioning under CVS. A project-level README configuration file should be maintained. SIT requests that development teams conscientiously follow these instructions.
Testing
Development teams should select environments appropriate for their application. The following two environments are required as a minimum:
• DEV – development: developer desktops • PRD – production
At least one of the following three should be used:
• UNT – unit testing: application component • REG – regression testing: whole application (PeopleSoft) • STG – staging testing: resource utilization and performance charactertistics
The following two are also available as needed: • CNV – conversion testing: resource conversion to new replacement resource (PeopleSoft) • TRN – training: production-like training sessions
SIT strongly recommends that teams match environments with appropriate resources in development, selected testing, and production phases.
Load Balancing
J2EE Development Standards v1.4 - 25 - Computational loading among distributed services can be more nearly balanced when a few implementation issues are observed. SIT recommends that development teams
• implement session objects as Serializable • limit core objects stored in the HTTP Session • remove session objects when they are no longer needed • do load testing
J2EE Development Standards v1.4 - 26 - J2EE Development Standards: References and Links
• Sun J2EE Platform
Java 2 Platform, Enterprise Edition
• UIS Java Resource Page
Installing J2EE Products
Installing UIS Java Standard Libraries
IU J2EE Release Preparation
CVS Configuration and Setup
UIS CVS Release Standards
• Coding Conventions
Code Conventions for the Java Programming Language: Sun Website
“Elements of Java Style” Allan Vermeulen et al; Cambridge University Press, 2000 ISBN 0-521-77768-2
• Unified Modeling Language (UML) and Rational Unified Process (RUP)
UML Resource Page
UML Resource Center
UML Training for Designers SIT Training Powerpoint
“Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design” Craig Larman; Prentice Hall PTR; 1998 ISBN 0-13-748880-7
Rational Unified Process
J2EE Development Standards v1.4 - 27 -
Rational Unified Process Whitepaper: Best Practices for Software Development Teams
• Design Patterns
//ads/uis/Groups/SIT/Design Patterns/ DAOPattern.pdf: “J2EE Data Access Objects” Design Java.pdf: “The Design Patterns Java Companion” langspec-2.0.pdf: “The Java Language Specification, Second Edition”
• Open Source Resources
Apache Software Foundation
Jakarta Apache Project
Ant Build Tool
ObjectRelationalBridge (OJB)
J2EE Development Standards v1.4 - 28 - J2EE Development Standards: Appendices
SIT recommends that developers keep transactions as small and as fast as possible. For example, do not wait for user input in the middle of a transaction. Also, make sure all required resources are available, before entering the try block.
Transaction Management in JRF
By default the JRF framework, which is currently the recommended framework to wrap database calls, does not execute consecutive database calls in a single transaction. If the desired behavior is that a section of code be inside of a transaction, a JDBCHelper must be passed along with the JRF method call. An example is provided below.
// A transaction must occur within a try block. A JDBCHelper must be // defined outside of the try block, so that it can be closed properly // inside of its finally block (as mentioned elsewhere in this document). JDBCHelper helper = null; try { // Get a helper from the pool and start the transaction. // Utilities is an application-specific object, so how you get a // helper in your application may vary. helper = Utilities.getJdbcHelper(); helper.beginTransaction();
// Do all of your transaction work here, remembering to pass // along the helper to each of the JRF calls. // See the JRF documentation for more help on passing helpers.
......
// End the transaction code helper.endTransaction(); } catch(ClassNotFoundException cnfe) { LOG.error("error in
J2EE Development Standards v1.4 - 29 - { if (helper != null && helper.getConnection() != null) { helper.getConnection().close(); } } catch (Exception e) { LOG.error("error in
Transaction Management Example in OJB
By default the OJB framework does not execute consecutive database calls in a single transaction. If the desired behavior is that a section of code be inside of a transaction, a PersistanceBroker must be passed along with the OJB method call. An example is provided below:
PersistenceBroker broker = null;
try { broker = PersistenceBrokerFactory.defaultPersistenceBroker(); broker.beginTransaction();
// do some database work with broker (i.e. broker.store(Object))
broker.commitTransaction(); }
catch (OJBRuntimeException e) { LOG.error(e.getMessage(), e); }
/* see hierarchy of org.apache.ojb.broker.OJBRuntimeException * exceptions for more specific exceptions you can catch. */
finally { if (broker != null) { broker.close(); } }
J2EE Development Standards v1.4 - 30 -