PRAISEFOR

TheJAVAEEArchitect’sHandbook“DerekAshmorehasassembleda‘musthave’bookforanyone

workingwithJavaand/orJavaEEapplications.Mr.Ashmorecoversallthebasesinthis‘howto’approachtodesigning/developing/testing/andimplementingJavaEEapplicationsusingJava

withfrequentreferencestoXML,JDBClibraries,SOAP,relationaldatabaseaccess

(usingSQL),andreferencesvarioususefultoolswhenrelevant.Thisbookclearlyillustrates

Derek’sexpertiseintheJavaworld....ThankyouforsharingyourknowledgewiththeIT

communitywithsuchausefulbook.”

DANHOTKA,AUTHOR/INSTRUCTOR/ORACLEEXPERT“THISBOOKISVERYWELLCRAFTEDANDEXPLAINSEVERYTHINGYOUREALLYNEEDTOKNOWINORDERTOBEASUCCESSFULANDPRODUCTIVEJAVAEE

ARCHITECT.ITISANEXCELLENTBOOK,WHICHOFFERSAFULLANDDETAILEDCOVERAGEOFTHETOPICOFJAVAEEARCHITECTUREANDCANBEUSEDASAHANDBOOKBYTHENOVICEORASAREFERENCETOOLFOR

THEEXPERIENCEDARCHITECT.THESTRAIGHTFORWARDWRITINGSTYLEANDGOODVISUALSMAKEFORAQUICKANDCOMPREHENSIVELEARNINGEXPERIENCE.IFJAVAISYOURPRIMARYPROGRAMMINGLANGUAGE,

ANDYOU’RECURRENTLYWORKINGASAJAVAEEARCHITECTORCONSIDERINGITASAFUTURECAREER,THISBOOKSHOULDBEINYOURLIBRARY.”

IANELLIS,VICEPRESIDENTANDCHIEFINFORMATIONOFFICER,IESABROAD“[DEREKHASWRITTEN]ANIN-DEPTHANDCOMPREHENSIVERESOURCEFORTHEJAVA2ARCHITECT!THEBOOKPROVIDESACONCISEROAD

MAPFORREAL-WORLDJAVAEEDEVELOPMENT.THEAPPROACHISPRACTICALANDSTRAIGHTFORWARD,BASEDONAWEALTHOFEXPERIENCE.ALLASPECTSOFPROJECTMANAGEMENT,APPLICATIONANDDATA

DESIGN,ANDJAVADEVELOPMENTARECOVERED.THISBOOKAVOIDSTHE‘DRYSTYLE’ANDOVER-

ABSTRACTION(OVER-SIMPLIFICATION)COMMONTOSOMANYBOOKSINTHISSUBJECTAREA.ANAWESOME

BOOK,IKEEPITONMY‘A’SHELF!”

JIMELLIOTT,CTO,WESTHAVENSYSTEMS,INC.

“Clear reading and bridges the gap between professionals and professors. I’ve read manytechnicalbooksinmythirty-yearcareerwheretheauthorspendsmoretimetossingaroundthecurrentbuzzwordsandfailstogetthepointacross.Derek’sbookreallyconnectswiththehardcoredeveloper.Practical,knowledgeable,excellentexamples.”

JOHNRMULL,PRESIDENT,SYSTECHSOFTWAREPRODUCTS,INC.

©2014byDerekC.Ashmore.Allrightsreserved.

Editor:CathyReedCoverDesign:TheRobertsGroupInteriorDesign:TheRobertsGroupIndexer:TheRobertsGroup

Publishedby:DVTPressBolingbrook,ILsales@dvtpress.comhttp://www.dvtpress.com

Allrightsreserved.Nopartofthisbookmaybereproducedortransmittedinanyformorbyanymeans,electronic ormechanical, including photocopying, recording or by any information storage and retrievalsystem,withoutwrittenpermissionfromtheauthor,exceptfortheinclusionofbriefquotationsforareview.

Theopinionsandviewsexpressedinthisbookaresolelythatoftheauthor.Thisbookdoesnotnecessarilyrepresenttheopinionsandviewsofthetechnicalreviewersorthefirmsthatemploythem.

TRADEMARKS: Java, Java EE, Java Development Kit are trademarks of Oracle Corporation, Inc. Allotherproductsorservicesmentioned in thisbookare the trademarksorservicemarksof their respectivecompaniesandorganizations.

Whileeveryprecautionhasbeentakeninthepreparationofthisbook,theauthorandpublisherassumenoresponsibilityforerrorsandomissionsorfordamagesresultingfromtheuseoftheinformationcontainedherein.

Contents

PrefaceHowtheBookIsOrganizedCommonResourcesFeedback

Acknowledgments

SectionI:PlanningJavaEEApplicationsChapter1:ProjectDevelopmentTeamandProjectLifeCycle

ProjectDevelopmentTeam:RolesandResponsibilitiesProjectLifeCycleApproachesFurtherReading

Chapter2:DefiningtheProjectIdentifyingProjectScopeIdentifyingtheActorsWritingUserStoriesWritingUseCasesCommonMistakesPrototypingSwim-laneDiagramsNonfunctionalRequirementsImprovingYourAnalysisSkillsFurtherReading

Chapter3:ScopeDefinitionandEstimationDefiningScopeBasicsofEstimatingTrackingtheEstimateNonfunctionalRequirementConsiderationsFurtherReading

Chapter4:DesigningExternalApplicationInterfacesStrategiesforConsumingExternalApplicationDataCommonMistakesDeterminingaDataStructureError-HandlingRequirementsExternalInterfaceGuidelines

SectionII:DesigningJavaEEApplicationsChapter5:ALayeredApproachtoJavaEEDesign

OverviewoftheLayeringConcept

DataAccessObjectLayerEntityObjectLayerValueObjectLayerBusinessLogicLayerDeploymentLayerFurtherReading

Chapter6:CreatingObjectModelsIdentifyingObjectsObjectIdentificationExampleTurningObjectsintoClassesDeterminingRelationshipsIdentifyingAttributesIdentifyingMethodsShortcutsExample:Admin4JFurtherReading

Chapter7:CreatingtheDataModelKeyTermsandConceptsDesignPracticesandNormalFormCreatingDatabaseSchemaDefinitionsCommonDatabaseDesignMistakesImprovingYourDataModelingSkillsCreatingXMLDocumentFormatsCommonXMLDesignMistakesFurtherReading

Chapter8:PlanningConstructionTaskOrderandDependenciesCommonMistakesImprovingyourProjectPlansandEstimatesFurtherReading

SectionIII:BuildingJavaEEApplicationsChapter9:CodingValueObjectsandEntities

ImplementationTipsandTechniquesValueObjectsMadeEasyCommonMistakesExample:Admin4JDifferencesfromtheFirstEdition

Chapter10:BuildingDataAccessObjectsTransactionManagementStrategiesDataAccessObjectCodingGuidelinesAJDBCExampleXMLAccessObjectCodingGuidelinesAnXAOExampleFurtherReading

Chapter11:BuildingBusinessObjectsBusinessObjectCodingPatternsBusinessObjectCodingGuidelinesABusinessLayerClassExampleAnAdmin4JBusinessLayerExampleFurtherReading

Chapter12:BuildingtheDeploymentandPresentationLayersWebApplicationFrameworkConsiderationsSecurityConsiderationsError-handlingConsiderationsSupportingMobileDevicesCodingGuidelinesCommonMistakes

Chapter13:MakingTechnologyProductSelectionsProductDecisionCriteriaMakingaProductDecision

Chapter14:BuildingArchitecturalComponentsComponentQualityMakingComponentsEasytoUseMakingComponentsEasytoConfigureandControlOpenSourceAlternativesComponentUsageGuidelines

Chapter15:ApplicationArchitectureStrategiesLoggingStrategiesException-handlingStrategiesAsynchronousTaskStrategiesConfigurationManagementStrategiesCachingStrategiesFurtherReading

SectionIV:TestingandMaintainingJavaEEApplicationsChapter16:TestingGuidelinesandStrategy

UnitTestingGuidelinesIntegrationTestingSystemIntegrationTestingUserAcceptanceTestingPerformanceTesting

Chapter17:MakingJavaEEApplicationsSupportableApplicationSupportObjectivesStreamliningInvestigationsforApplicationDefectsStreamliningInvestigationsforUnplannedOutagesAssessingApplicationQualityIdentifyingRefactoringOpportunities

Chapter18:FindingYourWayWhenTechnologiesChangeSimplerIsBetterReuse—Don’tReinventEnforceSeparationofConcernsSwimwiththeStreamCatchErrorsEarlierRatherthanLaterFunctionalRequirementsAretheHighestPriority

AbouttheAuthor

Preface

TheJavaEEArchitect’sHandbookwaswritten for application architects andseniordeveloperstaskedwithdesigningandleadingthedevelopmentofJavaEEapplications. The objective of this book is to help you fulfill the applicationarchitectroleinaJavaEEproject.Ifyouareaseniordeveloperneedingtofillthe role of an application architect for the first time, this book will help yousucceed.Ifyouarealreadyanapplicationarchitect,thisbookwillempoweryouwith additional skills so that you can improve your ability to fulfill that role.This book provides numerous strategies, guidelines, tips, tricks, and bestpractices to help the junior architect navigate the entire development process,fromanalysisthroughapplicationdeploymentandsupport.Tohelpyouachievesuccess as a Java EE application architect, the book presents the followingmaterial:

AbasicframeworkforfillingtheroleofapplicationarchitectateverystageoftheprojectlifecycleArchitect-leveltips,tricks,andbestpracticesateachstageofdevelopmentTips,tricks,andbestpracticesforestablishingcodingstandardstomakecodeconsistentandmoremaintainableTips,tricks,andbestpracticesforcreatingandcommunicatingdesignsEstimationandproject-planningmaterial

This edition of the handbook concentrates on application architectdeliverables at eachstageofdevelopment.That is, thebookdescribesdiscretetasks typically performed by the application architect and provides tips andtechniquesforperformingthesetasks.Asmanylearnbestbyexample,thisbookwillprovideexamplesofyourdeliverables.

Readers of the first edition might be confused by the title change for thesecond edition. The first edition of the book was titled The J2EE Architect’sHandbook.Theterm“J2EE”wasdeprecatedin2006andreplacedwiththetermJavaEnterpriseEditionor“JavaEE” for short.Essentially,both terms refer tothesameplatform.

Thisbookwillnot teachyouhow to program JavaEE applications.Whilemostapplicationarchitectsdocodepartsof theapplications theysupport, theydo so in their capacity of a developer, not in their capacity of applicationarchitect. The marketplace is replete with technical books that provideinstruction on how to code JavaEE applications.This bookwill complement,but not attempt to duplicate, that material.While there is sample code in thebook, its purpose is to illustrate application architecture concepts; not to be adetailedinstructionalguideonhowtowritecode.

ThisbookisnotastudyguideforanyofthecertificationexamsforJavaandJava EE technologies provided by the Oracle Corporation. Those examsconcentratepurelyontechnicalskills.Whiletechnicalskillsarenecessarytobeaneffectiveapplicationarchitect,theyarenotsufficient.Theroleofapplicationarchitect transcends raw technical ability. Architects must be effectivecommunicators,mustworkwellwithotherteammembers,andmustbeabletounderstand the business aspects and requirements for the end user areas theirapplications support. None of these facets of being an effective applicationarchitectismeasuredbyanyofthecertificationexams.

Furthermore,thebookisnotforbeginners.ReadersshouldknowJavasyntaxandbasicJavaEEconceptsandhaveatleastanintermediateprogrammingskillsetandbasicexperiencewiththefollowing:

Relationaldatabases,SQL,JDBC,andaJPAimplementationsuchasHibernateJSPs,servlets,andexperiencewithatleastonewebframework(e.g.,Spring-MVC,Struts,JavaServerFaces)ExperienceworkingwithwhatarecommonlyopensourceprojectssuchasApacheCommons,Spring,Hibernate,andmanymoreExperienceworkingwithadevelopmentteamExperiencesupportingapplicationsnotwrittenbyyou

Acommonconception is that JavaEEapplicationsare incrediblycomplex.Authorsof technicalbooksandarticlesunintentionallysupport thisconceptionby providing incredible technical depth on aspects of Java EE not commonlyused. For example, many texts begin their discussions of enterprise beans bydescribing JavaEE transaction capabilities in great detail; however,most JavaEE applications make only limited use of Java EE transaction management

capabilities.Inthisbook,Istripawaysomeofthecomplexity(aspectsthatthemajorityofdevelopersrarelyuse)torevealhowrelativelystraightforwardJavaEEapplicationscanbe.Yourtimeistoovaluabletowastereadingaboutfeaturesandconceptsyou’llrarelyuseinthemarketplace.

HOWTHEBOOKISORGANIZEDThe first chapter of the book describes the role of the application architect inmostorganizationsandexplainshowtheprojectlifecycleillustratedinthisbookfits inwith Extreme Programming (XP), theRationalUnified Process (RUP),andotherpossiblemethodologies.

Section1detailshowtodefinetheprojectobjectivesusinguse-caseanalysis.Italsodiscusseshowtodefinescopeandcreateapreliminaryprojectplan.Theguidelines presented in this sectionwill help you successfully complete thesetasksthatarecriticaltoyourprojectcominginontimeandonbudget.Themostcommon reasons for project failures or cost overruns are poorly defined andmanagedobjectivesandscope,nottechnicalproblems.

Section 2 focuses on object-modeling and data-modeling activities,describing howdetailed they need to be and illustrating commonmistakes. Inaddition, youwill learn how to architect interfaceswith external systems andhow to refine the project plan and associated estimates. The modeling skillspresented in this section are critical to effectively communicating a design todevelopers.

Section3presentsimplementationtipsandguidelinesforallaspectsofJavaEE applications. You’ll learn how to layer your application to minimize theimpact of enhancements and changes. You’ll also become acquainted withseveralopensourcelibrariescommonlyusedtostreamlineapplicationcodeandthedevelopmentprocess.

Inaddition,section3detailsapplicationarchitecturedecisionsyou’llneedtomake regarding testing, exceptionhandling, logging, and threading, andyou’lllearn tips and techniques for implementingmajor sections of the design. Thefailure of an application architect to define implementation strategies andmethodologiescanslowdownaprojectsignificantlyandincreasethenumberofbugs.

Section 4 offers tips and guidelines for developing testing procedures andprocess improvement. These suggestions are directed at making yourapplications more stable and maintainable. In addition, you’ll learn the signs

warningyou that refactoring activities are necessary.Reading this sectionwillenableyoutomakeyourfutureprojectsevenmoresuccessful.

COMMONRESOURCESThisbookmakesfrequentreferencestothefollowingopensourceprojectsthatareoftenusedwithmanyJavaEEapplications:

ApacheCommonsLang(http://commons.apache.org/lang/)ApacheCommonsCollections(http://commons.apache.org/collections/)ApacheCommonsBeanUtils(http://commons.apache.org/beanutils/)ApacheCommonsDbUtils(http://commons.apache.org/dbutils/)ApacheCommonsIO(http://commons.apache.org/io)GoogleGuavaCoreLibraries(https://code.google.com/p/guava-libraries/)Hibernate(http://www.hibernate.org/)

Another open source project on which this book relies is Admin4J. TheauthoristhechiefarchitectandadeveloperofAdmin4J.Admin4Jisusedasanillustration for implementing the concepts presented in this book. Admin4Jbinariesandsourcecanbedownloadedathttp://www.admin4j.net.

Errata,examplesourcecode,andothermaterialsrelatedtothisbookcanbefoundathttp://www.dvtpress.com/.

Double-tapgraphicstodisplaythemseparatelyandenlargethem.Manyofthegraphicsinthisbookwillneedtobeenlargedtobereadable.

FEEDBACKI’m always interested in reading comments and suggestions thatwill improvefuture editions of this book. Please send feedback directly to me atderek.ashmore@dvtconsulting.com.Ifyourcommentorsuggestionisthefirstofitskindand isused in thenext edition, Iwillgladly sendyouanautographedcopy. Additionally, reader questions are sometimes selected and answered inentriesinmyblogathttp://www.derekashmore.com/.

Acknowledgments

This book couldnot havebeenwrittenwithout a large amount of assistance.Severalcolleagueshelpedtremendouslytorefinethebookconceptandeditthedrafts,thuskeepingmefrommassmarketingmediocrity.Theyhavemyundyinggratitude and thanks. I could not havewritten the bookwithout the assistancefromthefollowingpeople:MichaelLyons,D.ScottWheeler,ToddPagni,HaimIzrael,KenLiu,BudiKurniawan,PeeyushMaharshi,MohitGupta,RickMiller,ShawnRacinto,Michael Spicuzza, ScottKramer, Pradeep Sadhu, and SauabhGupta.

Many thanks to my editor, Cathy Reed, who painstakingly corrected mynumerous grammar mistakes and graciously pointed out places where myverbiagewaslessthanclear.ManythankstoSherryandTonyRobertsandtheircolleaguesattheRobertsGroupforfantasticcoverart,typesetting,indexing,andgeneralwizardrythatmakesthebookaestheticallypleasing.

Manythankstomywife,Beth,andmychildren,ZacharyandMorgan.TheyputupwithmusiccomingoutoftheofficeatallhoursofthenightwhileIwasworkingonthis.BethroutinelywatchedourchildrensothatIcoulddevotetimetowritingthisbook.

Iretainresponsibilityforanyandallerrorsthatremain.

SECTIONI

PLANNINGJAVAEEAPPLICATIONSTHEAPPLICATIONARCHITECTTYPICALLYASSISTSINPLANNINGJAVAEEAPPLICATIONSBYPARTICIPATINGINANALYSISACTIVITIES,DEFININGSCOPE,ANDESTIMATINGRESOURCES,AMONGOTHERACTIVITIES.THEARCHITECT’SROLEINTHEPLANNINGSTAGEVARIESGREATLYFROMCOMPANYTOCOMPANY.ALTHOUGHI’VETAKENTHEPERSPECTIVETHATTHEARCHITECTLEADSANDFACILITATESPLANNINGACTIVITIES,YOURROLEATANINDIVIDUALCOMPANYMAYBETO

ASSISTRATHERTHANFACILITATE.

Inthissection,youwilllearnhowto:

Facilitateanddocumentbusinessanalysis.Assisttheprojectmanagerindefiningprojectscope.Estimateneededtimeandresources.Defineanddesigninterfacestoexternalapplications.

The skills you learn here will enable you to apply the design techniquesdiscussedinsection2.

CHAPTER1

PROJECTDEVELOPMENTTEAMANDPROJECTLIFECYCLE

This chapter lays the foundation for building a successful first project, frominception to release. It begins by definingwhat an application architect is anddoes, and by summarizing how the architectworkswith other teammembers.The chapter continues with a look at a few alternative approaches to thedevelopment process. Still a subject of considerable debate, the definitiveprocess for building a successful project does not yet exist, leading manycompaniestoadoptahybridplan.

PROJECTDEVELOPMENTTEAM:ROLESANDRESPONSIBILITIESAllJavaEEdevelopmentteamsneedpeoplewithawidevarietyofskillstofillnumerous roleswithin the team.Among themany skill setsneeded tomakeaJavaEEprojectsuccessfulare:

ApplicationarchitectProductmanagerProjectmanagerBusinessanalystGraphicdesignerPresentation-tierdeveloperBusinesslogicdeveloperDatamodelerDatabaseadministratorDatamigrationspecialist

InfrastructurespecialistTestingspecialistTestautomationspecialist

Although the book focuses on the role of the application architect, thissectiondefinestherolesandresponsibilitiesofothermajorplayersontheJavaEE development team and describes the responsibilities of the applicationarchitectwithrespecttothoseroles.

Some organizations use different labels for the roles. For instance, aninfrastructurespecialistmaybecalledasystemadministrator;atestingspecialistmay be a tester; and some organizationsmay distinguish between a test teammanagerandindividualtesters.Regardlessofthetermsyouattachtotheseskillsets,makingallofthempartofadevelopmentteamgreatlyincreasestheteam’schancesofcreatingasuccessfulJavaEEproject.

Further,it’spossibleforonepersonontheteamtofillmanyrolesandforonerole to be co-owned by multiple people if the project is large enough. Someorganizations combine the roles of application architect and project manager.Someorganizationshaveaseniordeveloperdoubleasadatabaseadministratororasan infrastructurespecialist.Andsomehave thesamedevelopersworkonthe presentation tier as well as the business layer. Here I’m not trying torecommendaparticularteamorganizationbutmerelytocommunicatewhatskillsetsarenecessary,howevertheyareorganized.

ApplicationArchitectTheapplicationarchitectidentifiesthetechnologiesthatwillbeusedfortheproject. In many organizations, some technology choices are made at anenterpriselevel.Forinstance,manyorganizationsmakehardwareandoperatingsystemchoicesandsomesoftwarechoices(e.g.,theJavaEEcontainervendor)at an enterprise level. Commonly, choosing a language, such as Java, is anenterprise-leveldecision.

However,mostapplicationshavetechnicalrequirementsthataren’texplicitlyprovided in enterprise-level edicts. I make a distinction between technologychoicesmadeatanenterprise levelandthosemadefor individualapplications.Forexample,adecisiontousetheJavalanguageforallserver-sideprogrammingmightbemadeatanenterpriselevel,butadecisionaboutwhichXMLparsertousemightbelefttoindividualapplicationarchitects.Inmanyorganizations,thepeople making enterprise-level technology choices make up a group separate

fromtheJavaEEdevelopmentteam.Theapplicationarchitectiscommonlyresponsibleforidentifyingthird-party

packagesor utilities thatwill beused for a project.For example, the architectmight identify a need for a template-based generation engine and chooseApache’sVelocity.

Increasingly, organizations are differentiating between enterprise architectsand application architects. Enterprise architects assist with deciding whichsoftware products will be purchased and which will be built. An effectiveenterprisearchitectwillensurethatsoftwareproductsinusearealignedwiththebusiness goals of the enterprise.Enterprise architecture is out of scope of thisbook;additionalmaterialontheroleofenterprisearchitectscanbefoundatthefollowingURL:http://en.wikipedia.org/wiki/Enterprise_architect.

Theapplicationarchitectrecommendsthedevelopmentmethodologiesandframeworks of the project. Typically, the architect makes theserecommendations to the project manager. For example, a commonrecommendationistodocumentallanalysesinuse-caseformatandsupplementwithaprototype.Anothercommonrecommendation is todocument thedesignintermsofanobjectmodel.Someorganizationsdefinethemethodologiesusedatanenterpriselevel.

The application architect provides the overall design and structure of theapplication. Each developer brings to a project a unique set of preconceivedopinions, habits, and preferences. Synthesizing the input of this sometimeswidelydivergentgroup,theapplicationarchitectensuresthattheworkdonebyindividualdevelopersiscomplementary.

Ilikentheroleofapplicationarchitecttothatofanorchestraconductor.Allmusicians have differing opinions about how to interpret a given work. Theconductor provides the interpretation that will be used and works with themusicians to implement it. Depending on the development methodology, thedesignforeachfeaturemaynotoccurupfront. In thiscase, it is thearchitect’sjob toworkwithdevelopersas featuredevelopment isoccurring toassistwiththedesignandensuretheimplementationfitswiththeoverallarchitecture.

Theapplicationarchitectensuresthat theproject isadequatelydefined.Aproject analysismust be detailed and consistent enough to form the basis forbuilding an application. Typically, the application architect works with theprojectmanagerandbusinessanalysttodefinetheproject.

Theapplicationarchitectensures that theapplicationdesign isadequatelydocumented. Documenting the application design is a critical step inestablishingsoundcommunicationwithandamongdevelopers.Theprocessofcreatingdocumentation forces thearchitect to think through issues thoroughly.The final document enables management to add or change developers to theprojectwithout adversely encroaching on the architect’s time. For developers,documentationallowsthemtoproceediftheapplicationarchitectisabsentfromthe project for a limited period, and it enables them to work through designinconsistencieson theirownwithout consuming the timeofothermembersofthedevelopmentteam.Documentationalsohelpstoinsulatetheprojectagainsttheeffectsofpersonnelturnover.

Often, the size and scopeof theproject indicateshowextensive thedesigndocumentation needs to be. For example, a project containing less than 1,000hoursofworkusingtwodeveloperswillrequiremuchlessdocumentationthanaprojectcontaining100,000hoursofworkrequiringafifty-personteam.Thereisnoobjectiverulethatindicatesanoptimalamountforagivenproject.

I’ve seen many projects that were not documented, and this meant thatadding a developer was a major chore because the architect had to verballyconveythedesigntothenewcomer.Havingtocommunicatethedesignverballynegatessomeofthebenefitstobringingonadditionaldevelopers.

It should be noted that there are tools that provide limited support formanagingfeaturerequestsandworkassignedtofulfillthoserequests.ExamplesofsuchproductsareJIRA(https://www.atlassian.com/software/jira)andMingle(http://www.thoughtworks.com/products/mingle-agile-project-management).Suchtoolsareofgreatvaluefor largershopswheredetailedhistoryoncertainchangesisneeded.

The application architect establishes coding guidelines. Because individualdevelopershavecodingpreferences,codingstandardsneedtobearticulatedsothat the individual pieces are more easily brought together. The applicationarchitect is responsible for establishing project procedures and guidelines fortopicslikethefollowing(whicharecoveredinmoredepthlaterinthebook):

ExceptionhandlingLoggingTestingThreading

CachingConfiguration

The application architect identifies implementation tasks for the projectmanager. This role is especially important for Java EE projects because theyencompassamuchwiderrangeof technologies thandoother typesofsystemsprojects. Out of practical necessity, the application architect also helps theprojectmanagerwithprojectplanningandestimates.

It’s a good idea for application architects to at some point gain experiencemanaging small projects. This helps them understand typical projectmanagementchallengesfacedbythepersonintheprojectmanagerrole,andthisunderstanding will enable them to provide better support for the projectmanagerstheyworkunder.

The application architectmentors developers for difficult tasks. Typically,the architect is more experienced than the developers. In fact, it is notuncommon forapplicationarchitects toalso functionasa seniordeveloper fortheprojectstheyworkon.Whenthedevelopersrunintoatechnicalproblemthatslowsthemdown,thearchitectisoftentheonewhohelpsthemcreateasolution.Formanyprojects,thearchitectismoreofamentorthananimplementer.

Theapplicationarchitectenforcescompliancewithcodingguidelines.Beingtheonewhoestablishescodingguidelines, theapplicationarchitect is themostlikelytorecognizewhentheguidelinesarenotbeingfollowedandis thereforethelogicalchoicetoenforcethem.Aprojectmanager,whotypicallyischargedwith enforcement tasks, often does not have the technical experience torecognizecompliance.

Codereviewsareanexcellentenforcementmechanism.Itismuchharderforindividual developers to privately skirt team coding standards if other teammembers examine the code. I also leverage source control to streamline myreview of coding changes on a periodic basis. That is, most source controlproducts provide a feature that will notify you of check-ins by e-mail. As apracticalmatter,theattentionIpaytoindividualcheck-insdependsontheskillsetofthedeveloperdoingthecheck-in.Overtime,somedeveloperswillprovemorereliablethanothersandrequirelessoversight.

Code reviews are also an excellent learning tool for all members of thedevelopment team.Theapplicationarchitectdiscoversholes in thedesign,andallparticipantslearntipsandtricksfromtherestoftheteam.Typicallythemost

experiencedmember of the team, the application architect often facilitates thecode review.Tobemost useful, a code review should be held in a congenial,nonthreateningatmosphere.

It should be noted that there are source analysis tools, such as Checkstyle(http://checkstyle.sourceforge.net/), PMD (http://pmd.sourceforge.net/), andFindBugs (http://findbugs.sourceforge.net/) that provide automated reviewsupport. That is, they will examine your source and point out likely codingissues.Usually, Ineed tospend timeconfiguring these tools (e.g.,determiningwhichrulestoenforce)beforeformallyincorporatingtheminthebuild.

Theapplicationarchitectassists theprojectmanager inestimatingprojectcosts and benefits for management. Although this is usually the projectmanager’sresponsibility,mostprojectmanagersarelessexperiencedwithJavaEEtechnologiesandmaynotbeawareofeverythingthatneedstobedone.It’stheapplicationarchitect’sresponsibilitytoreviewtheprojectplanandmakesurethe project manager hasn’t forgotten any tasks. I often have the entire teamreview theprojectplanandI solicit feedback. It’sharder for teammembers tocomplain about an inadequate or inaccurate project plan if they had theopportunitytoreviewandcritiqueit.

Theapplicationarchitectassistsmanagementinmakingpersonneldecisionsfor developer positions. While personnel decisions are often viewed as amanagement function, the application architect is in a good position to assesstechnical competence.Mistakes in personnel decisions can cause considerabledamagetoprojecttimelines.

ProductManagerThe productmanager is responsible for the product and its requirements. Formost organizations, this position is staffed by the business area that theapplicationismeanttoservice.Fororganizationsbuildingsoftwaretomarketorselltootherorganizations,theproductmanagerisresponsibleforensuringthattheproductisbasedontheneedsofthemarket.

Theapplicationarchitect isresponsible forproviding technicaladviceandguidance to the product manager. The application architect works with thebusinessanalystsandtheproductmanager(s)tohelpdeterminewhatfeaturesarefeasiblewithintheapplicationorfeasibleforaspecificrelease.

ProjectManager

Theprojectmanagerisresponsibleforcoordinatingandschedulingalltasksforallmembers of the project development team.The projectmanagermust alsocommunicate current project activities and status tomanagement and end-userrepresentatives.Further,theprojectmanageracquiresanyresourcesormaterialsneededbytheprojectortheteammembers.

Theapplicationarchitect isresponsible forproviding technicaladviceandguidancetotheprojectmanager.Theapplicationarchitectassists theprojectmanager in identifying project tasks and the order in which they should becompleted. The architect also helps the project manager identify neededmaterialsandresources,includingguidingtheselectionofotherteammembersandvalidatingtheirskillsetsfromatechnicalstandpoint.

BusinessAnalystThe business analyst is responsible for working with end users to define theapplication requirements and the detail necessary to design and build theapplication.Becauseendusers anddevelopersoftenusedifferent terminology,thebusinessanalyst isresponsiblefor translatingcommunicationsbetweenendusersanddevelopers.Oftenthebusinessanalysthasexperienceonboththeend-usersideandtheinformationtechnologysideoftheenterprise.

Asaprojectprogresses, thebusinessanalyst’s rolediminishesbutdoesnotdisappear.Developerstypicallyhaveadditionalbusinessquestionsthatcometolightduringcodingandtestingactivities,andthebusinessanalystworkswiththebusinesssidetogetthesequestionsanswered.

The application architect is responsible for ensuring that the applicationrequirements determined by the business analyst are adequate. It’sunreasonable toexpect100percentof theanalysis tobecompleteandcorrect.Afterall,analysisistosomeextentsubjective.However,theanalysisneedstobecompleteenoughtowarrantproceedingwithdesign.

SolutionArchitectThe solution architect ensures that the application adheres to any technicalstandards enforced across the enterprise. For example, many organizationsstandardize the databases and application server software used. Should theapplicationteamencountertechnicalproblemsthathavebeensolvedelsewhereintheenterprise,thesolutionarchitectwillguidetheapplicationarchitecttowardre-usingwhathasalreadybeendevelopedintheenterprise.Sometimessolution

architects are organized by business area and are able to assist businessrepresentatives indecidingwhichapplicationdevelopmentefforts to fund. It iscommon for the application architect to fill this role, especially for smallerorganizations.

GraphicDesignerManyapplications,especiallythosethatarepubliclyavailable,needprofessionalgraphics or layout designers. Most developers, left to their own devices, canproducefunctionalwebpages,butthosepagesaretypicallyuglyandhardtouse.Graphicsdesignismoreartthanscience.Thegraphicdesignerwillfocusonuserinterfacedesign,graphics,andoverallusabilityof theapplication.Usually, thegraphic designer works primarily with the business analyst and otherrepresentatives of the business side to work out the design. But the graphicdesigner may also work with the presentation-tier developer to create aprototype.

Some larger organizations distinguish between a “graphic” designer and a“transactiondesigner.”The transactiondesignerwill design thepage flowandcontrols to fit the business process, as opposed to being concerned withaesthetics. Most organizations don’t distinguish between the two roles andcombinethemintoonerole.

The application architect is responsible for ensuring that the layout istechnicallyfeasible.I’veseenmanywebpagedesignsthatusetexteffectsthatareavailableinwordprocessorsbutarenotsupportedbyHTML—forexample,adesignusingtextrotated90degrees.Thearchitectisinapositiontocatchandcorrectthesekindsofproblemsearlyinthedevelopmentprocess.

Presentation-TierDeveloperThepresentation-tierdeveloperisresponsibleforcodingallHTML,Javascript,templatemarkup, JSPs, and/or servlets for anapplication. Ingeneral, anythingdirectly involved in producing the user interface is in the purview of thepresentation-tierdeveloper.Typically incollaborationwith the layoutdesigner,the presentation-tier developer builds the prototype and develops the workingversion.Andwith theapplicationarchitect, thepresentation-tierdeveloper andgraphicdesignerdeterminethestructureanddesignoffront-endnavigation.

The application architect is responsible for ensuring that design patternscanbemaintainedandextended.Navigationissuesareoftencomplexandcan

easilydegradeintohard-to-maintaincode.Theapplicationarchitectisinagoodposition to identify and correct maintenance issues as well as other technicalproblemsthatarise.

BusinessLogicDeveloperThebusinesslogicdeveloperisresponsibleforcodingall invisiblepartsoftheapplication, including enterprise beans, web services, batch jobs, businessobjects,anddataaccessobjects.Somepeoplerefertotheseinvisiblepartsastheserver-sidecomponentsoftheapplication.ThebusinesslogicdeveloperisoftenaJavaspecialistwhoworkscloselywiththeapplicationarchitectandassistsinperformancetuningasneeded.

Theapplicationarchitectprovidesguidanceforthebusinesslogicdeveloper.It’s important for business logic to be readily usable by the presentation-tierdeveloper.It’scommonfortechnicalissuesandproblemstoariseinserver-sidecomponents,whichareusuallythemostcomplexpiecesofanapplication.Thus,theapplicationarchitectoftenactsasamentortothebusinesslogicdeveloper.

DataModelerThedatamodelerusesinformationfromthebusinessanalysttoidentify,define,andcatalogalldatatheapplicationstoresinadatabase.Datamodelingtypicallyinvolvesdocumentingapplicationdatainentity-relationship(ER)diagrams.ThedatabaseadministratorthenusestheERdiagramstoproduceaphysicaldatabasedesign. Thus, it is common for the roles of data modeler and databaseadministratortobecombined.

Theapplicationarchitectisresponsibleforensuringthatthedatamodelisadequate.Aswithbusinessanalysis,it’sunreasonabletoexpectthedatamodeltobe100percent complete. If thedatamodel is largely complete and in thirdnormalform,futurechangesinthemodel(andthusthedatabase)arelikelytobeminor.

DatabaseAdministratorThe database administrator is responsible for formulating a database designbased on the business requirements for the application, and for creating andmaintaining database environments for the application. Typically, the databaseadministrator assists with performance tuning and helps the business logicdeveloper diagnose application development issues regarding data access.

Sometimes,thedatabaseadministratordoublesasabusinesslogicdeveloperordatamigrationspecialist.

Theapplicationarchitectworkswiththedatabaseadministratortoresolveany issues or problems involving database storage. However, the databaseadministrator primarily interacts with the datamodeler and the business logicdeveloper.

DataMigrationSpecialistSomeapplications,suchasthosefordatawarehousing,dependheavilyondatamigrated from other sources or from a legacy database. The data migrationspecialistwrites andmanages all scripts and programs needed to populate theapplication databases on an ongoing basis. When an application has fewmigration requirements, this rolemaynotbenecessaryormaymergewith thedatabaseadministrator’srole.

The application architect ensures that data migration requirements areprovided for the migration specialist. Working with the data migrationspecialist to solve any technical issues or problems thatmight arise is anotheraspectoftheapplicationarchitect’srole.

InfrastructureSpecialistThe infrastructure specialist is responsible for providing all development,testing, and production environments as well as the deployment methods. Aformal infrastructure for development and deployment saves lots of time andeffort. The idiosyncrasies involved in administrating containers, writingdeploymentscripts,andassistingotherdevelopersindiagnosingproblemswiththeirtestenvironmentsrepresentauniqueandchallengingproblemset.

Usually, the infrastructure specialist works with the organization’s systemadministratorsanddatabaseadministratorstoprovidetheseenvironments.Mostorganizationsprovideresourceprovisioningservicesthroughcentrallymanagedgroups.Forexample,inmostorganizations,theinfrastructurespecialistwouldn’tphysicallyinstallordefineabuildserver;heorshewouldspecifyrequirementsfor that build server and a system administratorwould actually define it. Thesame can be said for the physical creation of databases. The point is that theinfrastructure specialist is responsible for seeing that the environments getcreatedandproperlyconfigured.

Aninfrastructurespecialist isoftenessentialwhenyouareworkingwithor

designingacontinuousintegrationenvironment,areprovidingbuildautomation,oraredealingwithcomplexhardwareinfrastructuresthatinvolveclusteringandothernontrivialenvironmentsetup.

The application architect defines infrastructure requirements for theinfrastructurespecialist. The architectworkswith the specialist to determinethenumberandnatureoftheenvironmentsneededandwhatlevelofsupportisrequired for each environment.Many projects need at least one development,testing, and production environment. Some organizations combine the role ofinfrastructurespecialistwiththatofapplicationarchitect.

TestingSpecialistAtestingspecialististypicallyadetail-orientedpersonwhomakessurethattheapplicationproducedmatchesthespecificationsandisreasonablyfreeofbugs.Typically,atestingspecialisthasatleastabasicknowledgeofthebusinessarea.

The application architect works with testing staff to identify anyinfrastructure requirements and support needed. The project manager andthe business analyst usually work with the testing specialist to establish thecontentoftestplansandthetestingmethodology.Therefore,thearchitect’sroleintestingisusuallysupport.Forlargerdevelopmentefforts,thetestingspecialistrolecouldbestaffedbyentiretestingteamsandatestingmanager.

TestingAutomationSpecialistAtestingautomationspecialistisusuallynecessaryforlargerprojectswhereitisanticipated that multiple application iterations and versions of the applicationwillbedelivered.Thetestautomationspecialistcanscriptintegrationteststhatcanbeperformedaspartofanapplicationregression,andthatcanbeexecutedonaperreleasebasisoraspartofacontinuousintegrationenvironmentwheretestsareexecutedoneverysuccessfulbuild.

PROJECTLIFECYCLEAPPROACHESTherearedifferingschoolsofthoughtastowhattheJavaEEprojectlifecycleshould be. This section describes these schools of thought and presents mypersonalviewsonthetopic.Theguidelinespresentedinthisbookareintendedtobecompatiblewithanymethodology.

WaterfallApproach

Thewaterfall approachentailsperformingall analysisanddesign foraprojectbefore coding and testing. This approach was commonly used when mostdevelopmentwasmainframe-basedandisstilltheonemostcompaniesprefer.

Projects developed under thewaterfall approach tend to be large and havelongdelivery times.Hence, theyentailmore risk.Theseprojectsusuallydon’trequire business participants to learn as much technical terminology, and thebusiness-sideinterfaceistightlycontrolled.

Compared with other approaches, the waterfall approach to projectdevelopmentdoesnotprovidefeedbackasearlyintheprocess,butitdeliversamore complete solution. Waterfall projects tend to fit neatly into the budgetplanningcycle,whichmaybeonereasonforthepopularityofthisapproach.

Because of the length of time waterfall projects typically require, thebusiness requirements often change during the project. Project managers thenface a dilemma: if the project doesn’t changewith the business, the resultingapplicationwon’tprovideasmuchbenefit;andiftheprojectchangescoursetofollow business requirement changes, the time and resources needed for theprojectwillbenegativelyaffected.

AgileApproachesAgile approaches strive to separate a project into small component pieces thattypically need few resources. Thus, agile approaches are the antithesis of thewaterfallapproach.Agileapproachescanbeviewedasa“family”ofapproacheswithmanyvaryingimplementations.ThemostpopularimplementationofagilemethodsatthetimeofthiswritingappearstobeScrum.Otherexamplesofagileimplementations are Extreme Programming (XP), Lean, and Crystal. For thecontext of this discussion, I use Scrum as the primary example of agilemethodologiesasitappearstobethemostwellknown.

Thecentralobjectiveofagilemethodologiesistoreducethetechnicalrisksandprojectcoststhatplaguethewaterfallapproach.Agilemethodologiesusethefollowingassumptions:

Catchingmistakesearlierischeaperinthelongrun.Reducingcomplexityalsoreducestechnicalriskandischeaperinthelongrun.Shortiterationsleadtoimprovedreturnoninvestment(ROI)andtheabilitytomorequicklyadapttochangingbusinessrequirements.

Focusontestautomationresultsinmoreefficientuseofdevelopmentresources.

Agile approaches dictate that you break the problem up into many smallproblems(calledstories)thattakethreeweeksorlesstoimplement.Eachstoryisco-developedbytwoprogrammersusingonemachine.Theprogrammatictesttodetermineifthenewstoryfunctionalityworksisdevelopedandaddedtotheregression test suite when the story is developed. These programmers ignoreeveryaspectoftheapplicationexceptthestorytheyareworkingon.Abusinessparticipantisdedicatedtotheprojectandisimmediatelyavailabletoansweranybusinessquestionsthatarise.

Using pairs of programmers to code everything theoretically reduces theprobabilitythatanerrorsurvivestodeployment.Usingpairsalsotendstomakecodesimplerbecauseittakestimetoexplaintheconcepttoanotherperson.Themore complicated the algorithm, the harder it is to explain. The emphasis onreducingcomplexitymakesitlesslikelythatmistakeswilloccur.

The emphasis on testing, creating, and frequently running a regression testsuite catches mistakes early and reduces the probability that any change willinadvertentlyintroducenewbugsorhaveotherunintendedconsequences.

Scrum and other agile methodologies reduce risk by providing feedbackearly.Adevelopmentteamproceedingdownthewrongtrackwillbealertedandcorrectedearlier,whenit’smuchcheapertomakechanges.

RationalUnifiedProcessTheRationalUnifiedProcess(RUP)isaformalizeddevelopmentmethodology.MostRUPliteraturedescribesitasaniterativeapproach,butthat’sonlyhalfthestory.RUPemphasizesstartingwithrequirementsgathering,analysis,anddesignactivities for the entire project—including object and data modeling—beforeproceeding to construction. In this sense, RUP takes a waterfall approach toanalysis and design but an iterative approach to construction and delivery.Byencouragingearly requirementsgatheringandanalysis,RUPseeks tokeep theprojectalignedwithuserexpectations.

RUPmitigatesriskbyencouragingtheteamtodeveloptheriskiestportionsof theproject first,allowingmore time to recognizeandrespond to issuesandproblems.Italsoreducesreworkwhenthedesignrequiresalteration.

WhichApproachIsMostPopular?

I’m not prepared to declare any of these approaches “best.” They all haveadvantages and disadvantages. Thewaterfall approach appears to be themostcommonlyusedincorporateenvironmentswherebudgetingisparamount.Manycompaniesuse (and aremore comfortablewith) awaterfall approach to initialdevelopment andmajor enhancements.While enhancements aremore iterativewith thewaterfall approach, the iterationsize isusuallymuch larger thanwithagileapproaches.

Agilemethodologiesarerarelyusedinpureform.Thisisn’tajudgment;it’smerely an observation. Given that, measuring the adoption rate for agilemethodologiesisproblematic.Tworecentattemptstomeasureadoptionratesarethe following: http://visual.ly/agile-2012-state-union andhttp://www.klocwork.com/blog/agile-development/agile-adoption-an-update/.Fromthesesurveys,someobservationscanbemade.

Scrum appears to be themost popular of the agilemethodologies. This issubstantiatedbykeywordstatisticsfromGoogleTrends(figure1.1).However,italsoappearsthatorganizationsusingagilemethodologiesuseagileforsome,butnot all, of their development. It couldbe that differentmanagerswithin largerorganizationshavedifferentpreferences.Itcouldalsobethatsomeprojectslendthemselvestoagilemethodologiesbetterthanothers.

Figure1.1:SearchEngineKeywordTrendStatisticsforDifferentAgileMethodologies

Source:GoogleTrendstakenonNovember25,2013.

WhatIThink

This book is largely compatible with either approach. Scrum users and otheragile enthusiasts would merely choose much smaller iteration sizes than myillustrations.Becauseoneapproachrarelyhasamonopolyoncommonsenseandisrarelydevoidofdisadvantages,Ipreferahybridapproach.

Agile’s emphasis on testing has great value. I’ve adopted the practice ofcoding test sequences for everything I write and combining them into a fullregressiontest.I’veevenseenateamgosofarastoputafullregressiontestinthebuildandforcethedeploymenttofailifallthetestsdon’tpass.Ifindthatthemistakes avoided by this practicemore than pay for the extra time and effortrequiredtodevelopandmaintaintestscenarios.Havingsaidthat,I’vealsoseenorganizations invest inunit tests,only todiscard themwhenmaintaining thembecomestooresource-intensive.

Agile’stendencytoreduceprojectsizehasgreatvalue.Projectriskappearstobeproportional to thesizeof theunitofwork.Hence,reducingthesizeof theunitofwork reduces thebusiness riskofundertaking theproject. Idon’thaveempiricalevidence toprove this statement,but I’veobserved it in the fieldonseveraloccasions.

Agile’swaroncomplexityhasvalue.Simplerisbetter.Ignoringallstoriesbuttheoneyou’reworkingondoesproducesimplercode in theshort term.But italso introducesahigherprobabilityof rework (or refactoring, inmoremodernparlance), for which many projects have no budget. If refactoring isn’t doneproperlyor thedevelopersareunder timepressure, thecodecaneasilyendupbeing unnecessarily complex anyway. Also, many developers use the“complexity”excusetoignorebusinessrequirements.

RUP’s emphasis on centralized analysis anddesignhas great value. Someagile methodologies assume that developers can take a parochial view of thestorytheyareworkingonandignoreanythingelse.Thiscancausesomeamountof rework. All developers should really have a larger focus. Because RUPconcentrates analysis and design at the beginning of a project, it represents asensible compromise between a purely iterative approach and the waterfallapproach.

It is necessary to control communication with end users. Some agilemethodologiesassumethatanymemberofthedevelopmentteamshouldbeabletotalktoanend-userrepresentative.Developersandendusersusuallyhavevery

different perspectives and use different terminology. In practice, manydevelopershavetroubleadaptingtonontechnicalterminology;theysimplycan’ttranslatebusinessterminologyintotechnicalterminology,andviceversa.Somecentralizationofcommunicationtothebusinesssideisnecessaryasapracticalmatter.

FURTHERREADINGBeck,Kent.2000.ExtremeProgrammingExplained.Reading,MA:Addison-Wesley.

Brooks,FrederickP.,Jr.1995.TheMythicalMan-Month:EssaysonSoftwareEngineering,AnniversaryEdition,2nded.Reading,MA:Addison-Wesley.

Cockburn,Alistair.2007.AgileSoftwareDevelopment,2nded.Reading,MA:Addison-Wesley.

Kroll,Per,andPhilippeKrutchen.2003.TheRationalUnifiedProcessMadeEasy:APractitioner’sGuidetotheRUP.Boston:Addison-Wesley.

Larman,Craig.2004.AgileandIterativeDevelopment:AManager’sGuide.Boston:Addison-Wesley.

Johnson,HilaryandChrisSims.2012.Scrum:aBreathtakinglyBriefandAgileIntroduction.Dymaxicon.

Stephens,MattandDougRosenburg.ExtremeProgrammingRefactored:TheCaseAgainstXP.Berkeley,CA:Apress.

CHAPTER2

DEFININGTHEPROJECT

Thefirststepindevelopinganyapplicationisperforminganalysistodefineitspurpose,scope,andobjectives.AJavaEEapplicationisnoexception.Includinganalysisinthedevelopmentprocessisbasiccommonsense,butI’mcontinuallyamazedathowmanyprojectsmuddlethroughwithoutdefiningtheirtargetfirst.

Theapplicationarchitectisnotdirectlyinvolvedindefiningtheproject;thatis the jobof theprojectmanager,businessanalyst,andenduser.However, thearchitect is responsible for ensuring that the project is defined with enoughconsistency and detail that it can be physically designed and implemented.BecausemostothermembersoftheJavaEEdevelopmentteamdon’tknowwhatinformationisrequiredtodesignandimplementanapplication,theapplicationarchitectoftenfacilitatesprojectdefinitiondiscussions.

Theapplicationarchitectmustpossessanalysisskills.Withoutanalysisskills,an architectwill not be able to recognize theweak points and gaps in projectdefinition at the onset of the project, which is when those weak points arecheaper to address.On theotherhand, architectswith analysis skills aremorelikely to anticipate future feature requests because they are able to understandthe business processes involved.While no effortwill be put into constructingthoseexpected featuresbefore theyare requested,designchoicescanbemadethatwillmakeitpossibletoaddthosefeatureslater.Asanexample,ifIexpectthat at some point in the future the customers may be able to have multipleaccounts,althoughtheycan’ttoday,I’llmakedesignchoicesthatallowforthatpossibility.

IcanhearthegroansofdevelopersasIwrite.Technicalpeoplewanttohearmore about coding techniques than project definition and analysis-gatheringstrategies.Icompletelyunderstand.There’snothingIlikemorethanproducinggood code that does something useful. However, to get good code, you needgoodanalysisandgoodprojectdefinition.Myexperienceisthattheprobabilityofgettingusefulcodewithoutdoingdecentanalysisfirstisslimtonone.

Use-casesareanimportanttoolinanalysis.TheUnifiedModelingLanguage(UML)specificationwascreatedtodescribeanddocumentanalysisanddesignsfor systems that use object-oriented languages like Java. The main constructUML has for describing what an application will accomplish is the use case.Thischapterdefinesthetermusecase,guidesyouthroughwritingusecasesforaproject, lists somecommonmistakesmade increatingusecasesandhow toavoidthem,andpresentsanddiscussesanexampleofusecaseswrittenforoneproject.

This chapter does not contain a comprehensive synopsis of use caseswithrespecttotheUMLspecification.Ipresentthesubsetofthespecificationthatiscommonly used and is practical. For a thorough treatment of the UMLspecification,seeBooch,Rumbaugh,andJacobson(1999).

Althoughsomedevelopersdistinguishbetweenusecasesandrequirements,Isee no difference. Requirements are the specific features, written in businessterms, that an applicationmust provide. Therefore, requirements typically areusecaseswritteninsummaryform.

Ifyou’reusingagilemethodologies,suchasScrum,youcreateuserstoriesrather thanusecases.Bothconstructs fulfill thesamepurpose:communicatinguserrequirements.Userstoriesareabriefstatementofwhatauserdoesorneedstodowithanapplication.Forexample,“Theapplicationneedstoremembermylast product search and pre-fill the filters I specified last time; I do the samesearchmostofthetime.”Userstoriesdonotcontainenoughdetailtoallowforimplementation;verbal communicationwith theuser representative is requiredtoflushoutthedetails.Usecases,incontrast,haveenoughofdetailtoallowforimplementation.Whethertheuserwritesusecasesorarrivesattherequirementsusinguserstoriesandverbalcommunicationissimplyadifferenceinformandtactics.

Additionally, I like to prototype the user interfaces. A prototype is anexcellentvehicleforenablingthebusinesssideanddeveloperstounderstandthetargetof adevelopmentproject. I usuallyhaveno troublegetting thebusinessside interested in theprototypingprocessbecause itconcretelyrepresentswhatthey’regoingtoget.Prototypingalsohelpsrefinetheusecases.

Onceyou’vedefinedaproject’susecases(orstories),youcancreateafairlydetaileddefinitionoftheproject,writteninbusinessterms,thatbothdevelopersand businesspeople can understand. This allows the business side and anymanagement stakeholders to provide feedback early.Getting a formal sign-off

for theusecases inaparticularprojectenables theprojectmanager tocontainprojectscope.

IDENTIFYINGPROJECTSCOPEAhigh-levelprojectdefinitionandpreliminaryideaaboutscopeisneededbeforeuse-case analysis and prototyping exercises can be effective.Most developersare detail oriented andwill consider this high-level definition too vague to beuseful.Keepinmindthatthepurposeofthishigh-levelprojectdefinitionisonlytodeterminescopefortheuse-caseanalysis(notforcoding).

Hereisanexampleofahigh-levelprojectdefinitionstatement:

Buildasystemthatassistsprojectmanagersinplanningtasks,trackingtheactivitiesofeveryteammember,andestimatingcompletiondates.Theproject-trackingapplicationshouldallowtheusertodothefollowing:Defineaprojectanditstasks.Recordpeopleassignedtoprojecttasksandestimatethetimeneededtocompleteeachtask.Recordtheorderinwhichtaskswillbecompleted.Recordprojectprogressandmarktasksascompleted.Automaticallyscheduletheproject.Createreportsofprojectprogress.

Asvague and simplistic as the statement is, it provides a startingpoint foridentifyingactorsandconstructingusecases.

IDENTIFYINGTHEACTORSThefirststepinuse-caseanalysisistoidentifytheactors.Anactor istheusertypeorexternalsystemservicedoraffectedbytheusecase.Althoughthewordactorhasconnotationsofbeinganactualperson,aUMLactorcanbeanexternalsystemoranorganizationtypeorrole.

The following is a list of actors for a report generation application Iarchitected:

Trustcustomeruser

TrustcustomerorganizationBankingsupportuserReporttemplatedeveloperDocumentdeliveryapplicationinterfaceReporttemplatedefinitioninterfaceDatawarehouseapplicationinterfaceReportrequestapplicationinterfaceApplicationadministrator

Andhere’salistofactorsforacash-trackingapplicationIarchitected:

CashmanageruserTransactionapproveruserSeniortransactionapproveruserBankingsupportuserFundaccountingapplicationinterfaceApplicationadministrator

YoumayhavenoticedthatineachexampleIlistedindividualusergroupsasseparate items. I did this primarily because every user group has differentcapabilities.While some use cases apply to all types of end users, others areuser-group specific. In each example,we had far fewer different types of enduserswhenwestarteduse-caseanalysisthanwehadwhenwefinished.Duringthecourseofwritingtheusecases,webegantorealizethatthereweredifferentuserrolesthatrequireddifferentcapabilities.

Itispossibleforausertorepresentmultipleactors.Forexample,auserwhoprovides banking support may also assume the role of a cash manager ortransactionapprover.

Consider the application administrator as an actor for any largeapplication.Thisforcessomeattentiontosupport—whichincreasesavailabilityandinturnmakesotheractors(whohappentobepeople)happy.

Make sure that all actors aredirect. Sometimes people are confused by the

externalsysteminterfacesandwanttolistasactorstheendusersservicedbyanexternal interface. For example, if a security-trading system is one of theexternalinterfaces,youmaybetemptedtolisttradersasactorsbecausetheyareservicedindirectlybyyourapplication.However,thesecurity-tradingsystemistheactor,andthetradersareindirectendusers.

Facilitate identifying actors by beginning with a small group. Applicationarchitects and business analysts can facilitate the discussion by makingassumptionsaboutwhotheactorsareandreviewingthemwithothermembersofthe teamand the business side. Inmy experience, people aremuchbetter andquickeratcritiquingsomethinginplacethantheyareataddingtoablanksheetof paper. You will probably discover additional actors as use-case analysisproceeds.

WRITINGUSERSTORIESAuser story is a short description that contains an actor, that actor’swant orneed,andtheexpectedbenefittheactorwillexperiencewhenthatneedismet.Usually, user stories are one sentence. User stories do not contain enoughinformation for developers to implement the feature. The intention is that thedetails needed to implement the feature are obtained in conversationwith thebusinessrepresentative.

Acommonformforuserstoriesisasfollows:

Asan<actor>,Iwant<wantorneed>[sothat<expectedbenefit>].

Someconsider the “expectedbenefit” part of theuser story to beoptional,whereas the actor and short description of the want or need is required.Examplesofuserstoriesfromsomeofmyrecentprojectsare:

Asaregistrar,Iwanttoproducetranscriptsthatcanbedistributedelectronicallybecausethat’swhatstudentswant.Asasecurityadministrator,Iwantareportthattellsmewhichusershavewhichrole.Asanexecutive,Iwanttobeabletoattachcommentstobudgeteditemstocommunicatewithotherexecutivesandaccounting.Asanacademicadministrator,Iwanttobeabletopublishclasssyllabi

storedinourcourseapplicationforprospectivestudents.Asanapplicationadministrator,Iwouldliketobenotifiedbytextwhenanout-of-memoryconditionisreached.

Additionalrequirementsobtained inconversations shouldbedocumented.Unless the project is very small and your organization is devoid of corporatepolitics, you need a written record of the implementation details. Thedocumentationdoesn’thavetobeelaborateorlengthy.Ensurethatyoushareitwiththebusinessrepresentative(s)youconversedwithtoobtaintheinformation;if there is amisunderstanding about the requirements, it’s best to flush it outearly.

WRITINGUSECASESAusecase isadescriptionofsomethingasystemdoesat therequestof,or inresponseto,anactionbyoneofitsactors.Youshouldwriteusecasesinbusinessterms,nottechnicalones.Anyoneonthebusinesssideshouldbeabletoreadthetext without a translator or technical glossary. Use cases containing technicalterms often indicate that technical design assumptions are beingmade at thisstage, and they shouldn’t be. Use cases can also serve as a casual “contract”betweenthebusinessanddevelopmentsidesoftheorganizationastowhatwillbedeliveredinwhatincrements.

Thereisnospecificformatforausecase.However,usecasesusuallycontaina title, description, actor list, precondition list, trigger,main process flow, andalternativeprocessflows.

Use-case description text should begin with: “The system (or application)will...”Ifyouidentifyausecasethatcannotbewritteninthisform,it’slikelynot a valid use case but rather part of another one. Note that use cases oftenservicemultipleactors.Irecommendexplicitly listingallaffectedactors in theusecase.

ThefollowingareexamplesofusecasedescriptionsfromareportingsystemIimplemented:

ThesystemwillprovideaninterfacethatwillallowuserstorunreportsfromdatadefinedinanexistingMVS/CICSapplication.Thesystemwillallowapplicationadministratorstocontrolthereportsthatmembersofatrustcustomerorganizationcanrun.

Thesystemwillallowapplicationadministratorstodefinenewreportsandpublishthemtousers.

Anactorlistdescribestheuserswhodirectlyparticipateintheusecase(seesection“IdentifyingtheActors”inthischapter).Somealsolistabriefreasonfortheactors’involvementinthisusecase.Anexamplemightbe:

Trustcustomeruser,whowantstoobtaininformationabouthisorherinvestments.Applicationadministrator,whowantstodefineadditionalreportsandpublishthemtocustomers.

Apreconditionlistisalistofbusinessconditionsthatmusttakeplaceforthisusecasetooccur.Examplesinclude:

Atrustcustomerhasbeenobtainedandisloggedin.Anewreporthasbeenrequested.

Atriggerisaneventthatstartsprocessingfortheusecase.Examplesinclude:

Atrustcustomerdesirestorunareport.Anapplicationadministratorstartsworkondefininganewreport.

Themainprocessflowofausecaseisastep-by-stepdescriptionofusecaseprocessingwithnoerrors.Anexampleforacustomerrunningareportmightbe:

1. Userdisplaysalistofavailablereports.2. Userselectsareporttorun.3. Userinputsanyparametersneededtorunthereport.4. Userinputsaformatforthereport(e.g.,HTML,PDF,Excel,etc.).5. Userviewsthereport.

Alternativeprocess flowsdescribe abnormal events that canhappenduringexecutionoftheusecase.

Iftheuserdoesn’tinputallrequiredparameters,thesystemwilldisplayanerrormessagelistingtheparametersthatarestillrequired.

Ifthereportexecutionerrorsout,thesystemwilldisplayagenericerrorpageandnotifyanapplicationadministratorwithdetailsoftheerror.

Usecasescanbewrittenwithamore formalorganizationandcontent.SeeCockburn(2001)formoredetails.

Usecasesshouldbeonetothreepagesinlength.ThelengthrecommendationisprovidedbyCockburn(2007).Usecasesthatarelongerthanthreepagestendtohavematerialthatisn’tappropriatefortheusecase;forexample,wireframegraphicsarenotgenerallyappropriatematerialforausecase.Lengthyusecasestendtocontainatermglossaryorwireframegraphics.Foreachusecase,Ifindit helpful to start with and include a summary that is no longer than twosentences.Thissimplifiesorganizingtheusecasesasthelistgrows.Asanalysisproceeds,youwillattachadditionaldetailtomostusecases.

Avoid use-case diagrams. The UML specification does define a graphicalrepresentation scheme for use cases. However, graphical schemes are rarelyused, and I purposely do not discuss them in this book. My experience hasshownthatuse-casediagramsconfuseboththebusinesssideanddevelopers,andthatthecostsofcreating,explaining,andmaintainingthesegraphicalconstructsfaroutweighanybenefitstheyprovide.

Writing use cases requires in-depth participation from the business side.Fromthetechnicalside,somebusinessanalystsmaybeabletohelpconstructaninitial draft, but the process should not end without direct business sideparticipationandreview.Althoughenlistingtheinvolvementofbusinessusersissometimes easier said than done, their input is valuable. In my experience,insufficientbusinesssupportforanalysiseffortslikeuse-casereviewcancauseaprojecttofail.

Facilitate use-case analysis by starting with a small group. Applicationarchitectscanspeedthisprocessalongbyworkingwithonebusinesssideuserorabusinessanalyst todraftasetofusecases thatcan initiatediscussion.Thesedraft use caseswill be incomplete, and somewill be incorrect, but you’ll getfeedbackeasierandquickerthanyouwouldifyoustartedwithablanksheetofpaper. You can use objections to your assumptions to refine and improve thedraftusecases.

Enlistsomeonetoactas“scribe”fortheuse-casediscussions.Whenyou’refacilitating a discussion, you won’t have time to take good notes. Having

someone other than the facilitatorwrite the discussion notes helps ensure thattheywillbecompleteandunderstandable.

Write use cases so they can be amended as more information becomesavailable.Usecasesarealwaysevolving.Ifyoudiscoveradditionalinformationinthemodelingphasesorinlaterportionsoftheproject,addthismaterialtotheusecases.

Use-case analysis is finishedwhen teammembers feel they can estimate atime to implement each use case. Estimates may be in terms of number ofweeks rather than hours. Some developers don’t feel comfortable providingestimatesuntilthey’veessentiallycodedtheapplication.Youmayneedtogentlyremind these developers that some difference between the estimate and theactual amount of time a task takes is expected. Note that it is common fordevelopers toonly includeanoptimisticdevelopment time in theirestimates; IhabituallydoubleestimatesprovidedbymanydevelopersIworkwith.

Donotslowdownifthegrouphastroublearticulatingrequirements.Makeassumptionsandproceed.Ifyourusecasesarenotright,theobjectorshavetheresponsibilitytotellyouwhat’swrongsoyoucancorrecttheproblem.Youcanusethatinformationtorefineandimprovetheusecases.

COMMONMISTAKESThissectioncontainsexamplesofusecasesthathavevariousdefects.

Imposinga technicaldesignassumptionunder theguiseofarequirement.This is the mistake I see most frequently. Consider the following use caseparaphrasedfromthereportingsystemexampleusedearlierinthechapter:

Thesystemwillallowapplicationadministratorstolimitsystemloadbysettingrulesthatprohibitreportexecutionforgroupsofusersorredirecttheirexecutiontoabatchstream.

Thisusecasemadeseveralunwarrantedassumptionsandhadussolvingthewrongproblems.Itassumedthatthehardware/softwarearchitectureusedbytheapplication could not be scaled to handle the load and that some alternativeprocessing route was necessary. It assumed that the application could not bemadeasefficientasthe“batchstream”mentioned.Anditassumedthatthebatchstream environment in fact had surplus capacity to handle load that the

applicationshouldhavebeenhandling.Evenifsomeoftheassumptionsmadeinthisusecaseturnedouttobetrue,

weshouldhavestartedbyplanninganarchitecturethatmorethansupportedourload. In fact, most of the assumptions turned out to be false: the architecturecouldhandle the loadefficiently; thebatchstreamwasa frequentperformancebottleneckand, infact,didnothavesurpluscapacity;andtheefficiencyof theapplicationmorethansatisfiedusers.

Abetterwaytowritethisusecasewouldhavebeen:

Thesystemwillsupportupto200concurrentlyrunningreportswithamaximumdailyvolumeof500,000reports.

Includingphysicaldesignassumptionsinusecases.Forexample,oneof thedeveloperssubmittedthefollowingusecaseforthereportingsystem:

Thesystemwillinsertarowintothereportrequesttableaftertherequestiscompleted.

Thisusecasemade thephysicaldesignassumption thatwewere recordingrequestrunsinatable.Butatthatpointwehadnotdecidedwhetherwewouldorwouldn’tdoso,andnorshouldwehave.Aftersomediscussion, I learned thatapplicationadministratorsneededawaytoknowwhatreportsauserransotheycouldreproduceproblemsatrustcustomerreportedtothehelpdesk.Giventheserequirements,abetterwaytowordtheusecasewouldhavebeen:

Thesystemwillrecordreportrequesthistoryforatleastthirty-sixhoursforthebenefitofapplicationadministratorsandreporttemplatedevelopersinvestigatingreportedproblems.

Notkeepinganalysissessionsproductive.Analysiseffortscanstall formanyreasons, including ineffective facilitationor leadership, anextremely low levelof detail in the discussion, and lack of information. It’s also possible forrequirements obtained from analysis sessions to be incomplete or otherwiseineffective.Applicationarchitectscansteerthedevelopmentteamawayfromallthese problems. Rather than see a session stall, I’ll create a “parking lot” foritems or issues to be addressed later, after additional information can beobtained.Parkinglotitemsaredocumentedandtrackedandthendiscussedatalatertime.

Failing to document use cases, even when the project is small. Mostdevelopersassumethatdocumentingusecasesisunnecessarywhentheprojecthasonlyonedeveloper.Theusecasesshouldbedocumentedanyway.However,with small projects, the use case set could be an informal one with a simplebulletlist.

Documentedusecasestargetthedevelopmenteffortandmaketangentslesslikely. Further, documented use cases communicate the objectives of thedevelopmenttomanagementandthebusinesssideandassistinprojecttransitionif additional developers join the team or the project is assigned to anotherdeveloper.

Repeatedly defining terms in every use case. Even for complicatedapplications, it’s unnecessary to define terms repeatedly in every use case inwhichtheyappear.Instead,youcandefinethemonceandthenmaintaintheminaseparatelistofbusinessterms.Forexample,cashtransaction(atermusedinan earlier use-case example) refers tomoney transferred from one account toanother.Thecharacteristicsofatransactionarethatithasanidentifier,adate,acashamount,atmostoneaccountfromwhichthemoneyistaken,andatmostoneaccounttowhichthemoneyistransferred.

Ifyouthinkwritingusecasesseemseasy,you’reright.Thecorollarytothisisthatifyouthinkyou’remissingsomethingandthatwritingusecasesshouldbeharderthanthischaptermakesitappear,you’remakingthetaskharderthanitneedstobe.Ifwritingusecasesrequiredmorethancommonsense,thepracticecould not be successful, because youwould never get a roomful of people toagreeontheoutcome.

PROTOTYPINGAtthisstage,thedevelopmentteamusuallyhasenoughinformationtochooseauser interface technology (which typically involves HTML because mostapplications are web-compliant these days). A user interface enables theprototypetobecomeapartoftherealapplicationandguardsagainstaccidentallypromisingdeliveryofsomethingthatisn’ttechnicallypossible.

Consider involving the layoutdesigner inproducing theprototype. In fact,the layout designer should facilitate this particular exercise instead of theapplication architect. I find that technicians usually don’t make the mostaestheticallypleasinguserinterfacescreens.IknowIdon’t.

Remember that prototypes are not functional by definition. None of theprototype screens should have dynamic data. If you are responsible fordeveloping the prototype and are using HTML, I highly recommend Castro(2006).

SWIM-LANEDIAGRAMSIt’snotapartofanyofficialmethodologythatI’mawareof,butI’vehadgreatsuccess supplementinguse cases andprototypeswith swim-lane diagrams thatdescribemajorbusinessprocesses.Forthosewhoaren’tfamiliarwithswim-lanediagrams, they describe business processes supported by the software beingdesigned. Each individual swim lane in the diagram contains an actor orapplication. Different components and decisions made during the businessprocessby thatactororapplicationaredenotedbyprocesssquaresordecisiontriangles within the swim lane. Swim lanes labeled with an actor are manualprocesses. Swim lanes labeled with an application are processes performedautomatically. The swim lanes are read left-to-right in chronological order.Figure2.1isanexample.

Figure2.1:SampleSwim-laneDiagram

I find that end-users readily understand swim-lane diagrams withoutdifficulty. They can effectively be used to describe which parts of a businessprocessaremanualandwhicharesupportedbysoftwareapplications.Endusersare comfortable with this approach as it allows them to easily see if they’veforgotten anything about the process that might be relevant to your project.Programmersalsobenefitfromthisapproachastheycaneasilyseethecontextinwhichtheirsoftwareproductwillbeused.

NONFUNCTIONALREQUIREMENTSAllprojectrequirementsdiscussedsofararefunctionalrequirements.Functionalrequirements define what the application is expected to accomplish.Nonfunctional requirements specify constraints on how the application willaccomplish functional requirements. For example, a functional requirementmight be that the application will allow a user to run a predefined report;whereasanonfunctionalrequirementmightbethatallpredefinedreportsshouldrunwithin sixty seconds.Another example: a functional requirementmightbethat the applicationwill allow a user to save a change to a customer account;whereasanonfunctionalrequirementmightbethatbackupneedstobetakenfor

the application and that any saved transaction needs to be recoverable in theeventofahardwarefailure.

Typically, there will not be use cases or user stories for nonfunctionalrequirements. However, nonfunctional requirements occasionally impactfunctional requirements. For example, I received a functional requirementenhancementrequesttoallowcustomerrepresentativestoviewusers’passwordsso they could communicate a user’s password if the user had forgotten it. Iinformedthemthattherewasamanagementdirectivethatpasswordswereneverto be stored in an unencrypted format. Furthermore, it was not possible todecrypt passwords with the encryptionmethod used. The directive to encryptpasswords in such a way that they cannot be decrypted is an example of anonfunctional requirement. In this case, anonfunctional requirementdefinitelyimpactedafunctionalrequirement.

IMPROVINGYOURANALYSISSKILLSSometimesdevelopersandjuniorarchitectshavetroubleacquiringthebusinessanalysisskillsneededtowritegooduserstoriesandusecases.Businessanalysisrequires good communication skills, both written and verbal, which not alldevelopershave acquired. It requires thatyoube able to express aproblem inbusiness terms, leavingall technical terms(e.g., file, field,etc.)behind. It’sanareathatisnotnearlyasobjectiveandpreciseascoding.Nonetheless,theabilityto write effective use cases and user stories is a skill all architects need todevelop.Ifyouthinkitnecessary,herearesomethingsyoucandotoimproveyouranalysisskills.

Getamentor.Choosesomebody,preferablyworkingatthesameorganization,whosebusinessanalysis skillsyou respect.Haveyourmentorprivately reviewyourusecases,userstories,orwhateverdocumentstyleyourorganizationusesto communicate functional requirements. Often, someone who is not directlyinvolvedismoreobjectiveandcanprovideyouwithvaluablefeedback.

Doapost-projectreviewforyourprojectsorassignments.Thisneednotbedoneformallyorpublicizedunlessyourmanagerrequeststhatyoudoone.Youcan gather this information informally by discussing the project with thedevelopersandend-userrepresentativesinvolved.Whatuserrequirementsweremissed?What could you have asked thatmight have identified thosemissingrequirementssooner?Thisisfeedbackyoucanuseandattempttocorrectwithin

futureassignments.

Imaginethatyouhadtodotheuser’staskdescribedbytheusecaseoruserstory.Whatwouldyouneedtodotoaccomplishtheusers’goalsifyouwereintheirplace?Doingthisexercisecanallowyoutoseeaspectsoftherequirementsyoumightbemissing.Also, itgivesyouinformationaboutwhat theuserdoesthatmightassistyouwithfutureassignments.

FURTHERREADINGBooch,Grady,JamesRumbaugh,andIvarJacobson.2005.TheUnifiedModelingLanguageUserGuide,2nded.Reading,MA:Addison-Wesley.

Castro,Elizabeth.2006.HTMLfortheWorldWideWebwithXHTMLandCSS:VisualQuickStartGuide,6thed.Berkeley,CA:PeachpitPress.

Cockburn,Alistair.2001.WritingEffectiveUseCases.Boston:Addison-Wesley.

Cockburn,Alistair.2007.AgileSoftwareDevelopment,2nded.Boston:Addison-Wesley.

Fowler,Martin,andKendallScott.2003.UMLDistilled:ApplyingtheStandardObjectModelingLanguage,3rded.Reading,MA:Addison-Wesley.

CHAPTER3

SCOPEDEFINITIONANDESTIMATION

Inmost organizations, the projectmanager works with the business side andmanagement to establish project scope and to estimate time and resourcerequirements. And frequently the project manager relies on the applicationarchitect forassistance in these tasks.Thescenario isnodifferent for JavaEEapplications. This chapter is written for architects responsible for helping todefine and estimate delivery for management. Readers not involved in thesetaskscansafelyskipthechapter.

DEFININGSCOPEObjectivelydefineproject scope in terms of user stories oruse cases, andobtain the agreement of the business side. Changing scope during a projectwreakshavocwithproject timelinesandlowersthemoraleofthedevelopmentteam.When the business side makes additional requests after development isunderway,acknowledgethem,recordtheminausecase,andschedulethemfora future release. Often, making rough estimates for each use case providesinformationthatthebusinesssidewillfindusefulindecidingscope.

Getagreementon theusecases from theproject sponsor.Asuse cases arewritteninbusinessterms,theycanbeusedasa“contract”withthebusinesssideandmanagementastowhatwillbedeliveredwhen.Workwiththebusinesssidetochoosewhichusecaseswillbeimplementedinthecurrentproject.Anythingelsewillbedeferred.Evenifscopeisagreedonverbally,putitinwritingande-mailittoeveryoneremotelyconnectedtotheproject.Makesuretokeepacopy.

Diligently enforce project scope once it’s determined. The most importantthingtheprojectmanagercandooncethescopeofaprojectisdeterminedistoenforceit.Theapplicationarchitecthastheresponsibilityofalertingtheprojectmanager toscopechanges. It’smuchharder tohitamoving target.AlthoughIgenerally prefer to schedule all enhancements for future releases, the architectusuallydoesn’tgettodecideschedulingissues.Iestimatetherequestinuse-case

formandprovideapreliminaryestimate.Usually, theprojectmanagercanusethis information to steer the business side toward scheduling the request for afuturerelease.

Document any assumptionsmade in determining project scope. There areusually unknowns about project requirements at this stage. Often it is notpossible to pause the project while the unknowns are investigated. In thesesituations,Imakemybestguessastowhattherequirementsareanddocumentthoseguessesasassumptions.Itisimperativethatmanagementandtheproductmanager or other business representatives be provided a copy of thoseassumptions. Should the assumptions be incorrect, you’ll be notified andchangestothescopeandresultingestimatecanbemade.

Inthecontextofagilemethodologies,suchasXPorScrum,the“project”ismore likely to be referred to as an “iteration” and tends to be of smaller size.Notethatmostagilemethodologiesadvocatefixingscopefortheiterationthat’scurrently in development. Agile methodologies accommodate change byproviding flexibility (allowing changes in scope) to iterations currently not indevelopment.

BASICSOFESTIMATINGManytechnicalpeopleconsiderestimatingdifficult;andindeed,atthisstage,itis definitely as much art as it is science. This chapter presents a method ofdetermining a gross estimate based on information you should have from theuse-case analysis and the prototypes. I make no claims that my way ofestimating is theonly way. If you have an approach you’re comfortablewith,staywithit.Itshouldbesaidthatestimatingthesameprojectmultiplewayscanvalidate your confidence in the estimate, particularly if the different methodscomeupwithsimilaranswers.

Estimates formed at the beginning of a project should be revisitedperiodically and refined after more detailed planning and designing are done.Afterdefiningtheexternalinterfacesandcompletingobjectanddatamodeling,youwillbeinabetterpositiontomakemoreaccurateestimates.Estimatesyoumakenowshouldbedetailedenough thatyoucanuse them inestimatinganycombination of use cases. Ideally, the business side looks at cost/benefitcomparisonswhendecidingonscope.

Estimateintermsoftheslowestresourceontheteam.Weallknowthatsome

peopletakelesstimeondevelopmenttasksthandoothers.Iwouldratherdeliveraprojectearlythanhavetoexplainwhyit’sgoingtobelate.

Estimates should be proportionally balanced. I have found that a typicaldevelopment team spends about one-third of its resource budget planning anddesigning, one-third coding and unit testing, and one-third supporting system-anduser-testingactivities.Keepinmindthatsomeportionof theplanninganddesign budget was spent performing the use-case analysis described in theprevious chapter (I usually assume that planning and design is 50 percentcompleteatthispoint).Theseratiosapplytotheentirelifeoftheproject.

Estimatesshouldbeexpressedintermsofthenumberofworkhours.Thatis, estimate in terms of the number ofwork hours needed to complete a task.Most projectmanagement softwarewill compute adatebasedonyourprojectplan.Ifresourcesaredivertedtootherprojects,you’llbeabletomoreaccuratelyadvisemanagementastotheresultingprojectimpactofthatdecision.

Considerthetimeneededtosetupthedevelopment,testing,andproductionenvironments. Most companies provide established environments at theenterprise level. For example, many companies have a central administrationteamtoestablishenvironmentsfordevelopment,testing,andproductionofnewapplications. If your company has such a team, time allocated to environmentsetupwillbelowandnotusuallymaterialforpreliminaryestimates.Ifthisisn’tthe case at your company, you should add an estimate for setting upenvironments.

Developersaremoresuccessfulatestimatingcodingandunit-testing tasksthananythingelse.Ifyoucangetareasonablecodingandunit-testingestimate,you can extrapolate the rest using the ratios mentioned previously and get aballparkestimate.Notethattoextrapolateatotalestimatebasedonthoseratios,you just multiply the coding and unit-testing estimate by 2.5, assuming thatplanninganddesignis50percentcompleteatthetimeyouestimate.

Validate your estimates by comparing them to historical data. I track thenumberofhoursittakestoactuallycompletethetasksthatwereestimated.Thatallowsme to identify estimatingmistakes and correct themon futureprojects.Consequently,Ihavealibraryoftasksfrompreviousprojectswiththetimetheyactuallytooktocomplete.Ilookforcomparabletasks(similaramountofworkwith similar difficulty) from this library. The estimates I’m evaluating for the

current project should be roughly congruent with what was experienced withthosecomparabletasks.Thisisthesamewayrealestateisvaluated.Realestateprofessionals estimate a property’sworth by looking at sale prices for similarproperties nearby. The same methodology works for software estimation formosttasks.

AnAlgorithmforEstimatingItshouldbenotedthatapplicationarchitectsareresponsibleforestimatinghoursonly. Project managers should be equipped to account for absences due toresponsibilitiestootherprojectsandvacations.

Step1:Quantifytheapplication;determinearoughnumberofwebpages,batch jobs, reports, database tables, and external application interfaces.Fromprevioushistory,youshouldhavetimesheetdataforcomparableprojects.From that historical data, derive an average number of hours to complete oneweb page (assuming that data access logic and business logicwill need to bedeveloped to support it). For example, with one of my current clients, myworkingaverage is forty toeightyhoursperdynamicwebpage,dependingoncomplexity. I have similar estimate ranges for batch jobs, reports, databasetables,andexternalapplicationinterfaces.Databasetablesareinthelistasthereare data modeling and database design steps to be performed as well asphysically creating the tables themselves. To derive a coding and unit-testingestimate, gather estimates of the following for the group of use cases beingconsideredfortheproject:

Screens/pagesintheuserinterface(40–80hourseach)Externalapplicationinterfaces(80–120hourseach)Databasetables(4–8hourseach)Conversionbatchjobs(24–40hourseach)

If this isyour first timeestimatingaproject, youmightnothavehistoricaldata from comparable projects to draw upon; in which case, ask one of yourcolleagueswhomight.Askyourmanageroroneofthepeopleyouworkwithforsampleprojectplansandestimatesfrompreviousprojects.

Notalltheseitemswillexistforeachusecase.Thebasicestimatesnotedinparentheses in thepreceding list areapplicable if thedevelopment teamhasn’tbeenformed.Ifthereisanexistingteam,moreaccurateestimatesforeachitem

maybepossible.Estimatesat thispointwillnotbeexact.Estimatingbasedonthenumberofobjectsismoreaccurate,butthatnumberisnotavailablebeforeobjectmodelingexercisesaredone.

Step2:Estimatecodingandunit-testingtimeforeachusecase.Basedontheinformationgatheredinstep1,itissimplemathematicstogetabaseestimateforacombinationofusecases.Thebaseestimate is thelengthoftimeit takesforone developer to complete coding and unit-testing tasks. It may seem a bitstrange toestimatecodingandunit-testing timebeforedesign iscomplete,butfewdevelopersseemtobebotheredbythisambiguity.

Many developers confuse unit testing with system testing. Unit testing isstrictlyataJavaclasslevel.Howwellaclassfunctionswhencalledfromotherclasseswithintheapplicationisintegrationtesting,notunittesting.

Forexample, fora setofusecases that involves four screens, twoexternalinterfaces, five database tables, no data conversions, and two environmentsetups,thebaseestimateis:

(4×80hrs)+(2×120hrs)+(5×8hrs)+(0×40hrs)+(2×8)=616hours

Step3:Multiplythebaseestimatefromstep2by2.5toaccountforanalysisandtestingactivitiesforeachuserstoryorusecase.Ifcodingandunittestingareaboutone-thirdoftheoverallcostofeachusecase,thetotalcostshouldbeabout three times the base estimate. Because the analysis is about 50 percentcomplete at this stage, estimate the total cost to be about 2.5 times the baseestimate. Continuing the previous example, the total hours left for the projectwouldbe600×2.5=1,500.

Step4:Inflatetheestimateby20percentforeachadditionaldeveloperontheproject.Thebaseestimateassumesthattheprojecthasjustonedeveloper.Each developer added to a project adds communication and coordination time(Brooks, 1995). Although necessary, time spent communicating andcoordinatingistimenotspentdeveloping.Therefore,inflatethebaseestimateby20percent(i.e.,multiplyby1.20)foreachdeveloperadded.Forexample,withabase estimate of 2,600 hours and five developers expected, estimate spending600×(1.20)4=1,244hourstocodeandunittest.Incidentally,it’sagoodideatoroundthatnumberto3,500toavoidcreatingthemistakenimpressionthatthisisanexactestimate.

Assuming the project’s five developers are dedicated full time (thirty-two

hours per week, allowing for bureaucratic distractions, etc.), the developmentteamcouldworkatotalof160hoursperweek.Thismeansthatprojectdeliverywouldbeapproximatelytwotothreemonthsout.Specificallystatetheestimateinmonthsorquartersatthispointtoavoidcreatingtheimpressionthatthisisanexactestimate.

Step 5: Review your estimates with the development team. If developersdon’t have input, they won’t feel bound by the estimates. It’s important toremind developers that these estimates will be reassessed after design iscomplete.

More manpower rarely saves a late project’s timeline. Thecommunication/coordination penalty, as previously described, is the primaryreason that adding people to a late project onlymakes it later. Architects areoftenaskedforballparkestimatesbeforealltheanalysisisdone.Evenifitwon’tbe literally correct, you can ballpark an estimate by filling it out withassumptionsanddocumentingthemwiththeestimate.

Thetimeyouspendestimatinghasdiminishingreturns.Nomatterwhat,theactualnumberofhoursyouworktocomplete theprojectwilldifferfromyourestimate. Applying more time to the estimation process will not make yourestimatemoreaccurateinmostcases.Thisisanuncomfortablethoughttomanydevelopersnewtoestimating,but it’soneof those truisms thatdevelopers justhavetolearntolivewith.

Those following agile methodologies with shorter development iterationswillhavelowerestimates.However, thesameconceptsapply.If thestoryis toadd a feature to an existing application, use estimates frompast storieswhereyouhavehistoricaldata.

TRACKINGTHEESTIMATEIf,inadditiontoyourapplicationarchitectrole,youarefillingtheroleofprojectmanager as well, you should track your progress against the estimate on aperiodic basis. Tracking your progress means gathering the number of hoursdevelopersareactuallyspendingonassignedtasksandcomparingthosehourstowhatwasestimated.

Estimatetrackingdocumentstheextenttowhichtheprojectison-timeandon-budget. Most projects don’t become two months late in one day—it’s a

symptomthatappearsover time.Mostexecutivescanaccommodatea timelineissueiftheyseetheproblemfarenoughinadvance.

Estimate tracking documents the effect of re-allocating resources to otherprojects.Bytrackingonlythosehoursthataredevotedtoyourproject,youcanalertmanagementifnotenoughtimeisbeinggiventoyourprojecttofulfillthetimeline. I’veoftenbeenable todefendprojects thatweredelivered later thanplanned by pointing out that they weren’t late at all in terms of the workperformed. The project was late because resources were allocated to otherprojects—notbecausetheteamwasmismanaged.

Tracking estimates enables you to improve them on future projects. Forexample, if I consistently underestimate the work involved in adding newscreens/pagestoanexistingapplication,Imayincreasemyestimatesforsimilartasksinfutureprojects.

Itendtotrackprogressweeklyandincludeaprogresssummary(whethermyteamisaheadorbehind)inmystatusreport.Trackingprogressweeklyisoftenenough to be useful tomanagement, but not so often that it consumes a largeamount of time. Publishing your progress in your status report ensures thatmanagement isn’t “surprised” by a late delivery. It also documents the effectshouldsomeofyourresourcesbedivertedtootherprojects.

NONFUNCTIONALREQUIREMENTCONSIDERATIONSAsexplainedinthelastchapter,nonfunctionalrequirementsplaceconstraintsonhow application requirements are met. As such, nonfunctional requirementsoften impactprojectestimates.Forexample, testingestimateswillbehigher ifthe application needs to support seamless fail-over in the event of a hardwarefail-over. If there is a nonfunctional requirement that the application must beable to support 50hits per second, thenperformance testing estimatesneed toreflect that. If there is an enterprisemandate that unit tests for an applicationmusthaveatleast90percentcodecoverage,thendevelopmentestimatesneedtoreflectthat.

FURTHERREADINGBrooks,FrederickP.,Jr.1995.TheMythicalMan-Month:EssaysonSoftwareEngineering,AnniversaryEdition,2nded.Reading,MA:Addison-Wesley.

DeMarco,Tom,andTimothyLister.1999.Peopleware:ProductiveProjectsandTeams,2nded.NewYork:DorsetHouse.

CHAPTER4

DESIGNINGEXTERNALAPPLICATIONINTERFACES

It iscommonforaJavaEEapplication to interfacewithexternalapplicationswe don’t control. For example, a purchasing application may notify anaccountingapplicationofallpurchases,oraninventorymanagementapplicationmay notify an accounting application of all inventory receipts and customershipments.Theapplicationarchitectisresponsibleforthedesignofapplicationinterfacesaswellastheapplicationitself.Applicationarchitectstypicallyhaveacentral role in designing application interfaces with external applications,especiallywhentheexternalapplicationisalsoacustomdevelopment(e.g.,notavendedproductwithestablishedinterfacecapabilities).Thischapterdescribeshowtodefineexternalapplicationinterfacerequirementssothatbothapplicationteamswillhave the informationneeded toperformdesignand implementationtasks.

Sometimesexternalapplicationsarevended,andsupportedinterfacemethodsare established and readily consumable. Sometimes external applications aresupportedbyanotherteamorbusinessareaanddon’tyetexist.Commonreasonsforcreatingexternalapplicationinterfacesareasfollows:

ToreadexternalapplicationdataforreferenceorprocessingToleverageexternalapplicationstoperformsomebodyofworkTopublishfunctionalitytoexternalapplications

Reporting applications are a common example of a need to read externalapplication data. Rarely do reporting applications maintain the informationneededforreportcontent.Itismorecommonforreportingapplicationstoreaddata as required. It is also common that userswant to reference data from an

externalapplicationwhenusingafeatureofanapplicationyou’rebuilding.Leveragingexternalapplication functionalityorpublishing functionality for

otherapplicationsareexamplesof theDon’tRepeatYourself (DRY)principle.In fact, they only differ in perspective; every “external” application is anapplication that somebody supports and they look at your application as“external.”Oftenitisnotcosteffectiveordesirabletoreplicatefunctionalityinthatexternalapplicationforaspecificuseinyourapplication.Forexample,let’ssay your application needs to initiate the recording of a customer charge.Nobodywritescustomaccountingapplications thesedays. It’smore likely thatyour application needs to leverage a vended accounting application to initiatethatcharge.

External interfacescreatestabilityrisk.Outages inexternalapplicationscancause partial outages for the application you’re supporting. Furthermore,changes in external applications (e.g., product upgrades or productenhancements) can also force changes in the applications you support.Consequently, implementing interfaces in a way that mitigates or containsstabilityriskisusuallyarequirement.Therearewaystomitigatetheserisks,andtheywillbediscussedinthischapter.

External interfaces complicate development and support activities.Development and support are impacted as problems require personnel outsidethe team to resolve. Furthermore, it is not always easy to determine whichapplicationownsaparticulardefect.Youmayinvestigateareporteddefectonlytodiscoverthatit’sreallyadefectintheexternalapplicationandallyoucandoisreporttheissuetotheteamorvendorthatsupportsthatapplication.Thereareways to reduce the complications external interfaces cause, and they will bediscussedinthischapter.

Application architects are typically responsible for ensuring that externalinterfaces are formally defined and documented so that developers from bothapplicationshaveabasisforobject-modelingactivities(describedinchapter6).Theapplicationarchitectsforbothapplicationsneedabasisfor theirmodelingand implementation activities. Further, the project manager needs a contractbetween your development group and the external system developers thatdescribeseveryone’sresponsibilities.

The following aspects of external interfaces should be discussed with theexternalteamsandagreedonamongtheteams:

Interfacemethodselection(e.g.,webservices,messaging)PublishedservicesorfunctionsDatacontentstructureTriggeringeventsforcontentexchangeError-handlingproceduresandresponsibilities

Theapplicationarchitectshouldfacilitateinterfacedesigndiscussions.Partof the role of facilitator is keeping the discussions limited to the topics justlisted. The internal design of either application is largely irrelevant to thisdiscussion.TheplatformusedbytheexternalapplicationisrelevantbecauseitcouldaffecttheabilityoftheJavaEEapplicationtousesomeinterfacemethods.For example, if the external application is not written in Java, the Java EEapplicationcannotuseanyformofcommunicationthatusesRMI,suchasEJBs.

This chapter will describe commonly used interface methods and theiradvantages and disadvantages to help guide you in making design decisionsaboutexternalinterfaces.

STRATEGIESFORCONSUMINGEXTERNALAPPLICATIONDATAThemostcommontypeofexternal interfaceisneededtoreaddatamaintainedbyanotherapplication.Commonlyusedstrategiesincludeutilizingtheexternalapplication database directly or utilizing an Enterprise Java Bean (EJB),Messagingtechnologies,RESTservice,orwebservicetoobtaintheinformationneeded.Eachofthesestrategieshasadvantagesanddisadvantages.

ReadingExternalApplicationDatabasesDirectlyTheadvantagesof thestrategyof readingexternalapplicationdatadirectlyarethefollowing:

IsthesimplestandcheapesttoimplementRequireslittleornoinvolvementfromtheexternalapplicationvendororapplicationteamProvidesdatathatisalwaysup-to-date

Thisstrategyisusedalotbecauseinitialdevelopmentisusuallysimpleand

cheap.Itoftendoesn’ttakemuchinteractionwithexternalapplicationpersonnel.Furthermore, database access is well known and easily understood by mostdevelopers.

Thedisadvantagesofthisstrategyarethefollowing:

IncreasedriskofadverseimpactfromexternalapplicationchangeIncreasedriskofunintendedconsequencesonexternalapplicationusers(i.e.,performance)

Reading external application databases directly makes use of applicationinternals that were never intended to be published in many cases. If externalapplicationsarevended,itiscommonforproductupgradestocontaindatabaseschema changes. If the external application belongs to a separate team ordepartment, changes might occur in the external application database withoutnotice. Consequently, it’s often desirable to reduce exposure to these types ofchanges.

WiththeexceptionofOracle,mostdatabasesissuelocksonreadsbydefault.Thismeans that readingdata isn’t necessarily harmless. It is possible that thisstrategyadverselyimpactsperformance(becauseofreadlocking)ontheusersofthoseexternalapplications.

The risks of reading external application databases directly can bemitigated by using an operational data store. Essentially, your applicationreadsacopyoftheexternalapplicationdatainsteadoftheexternalapplicationdatabase directly. This mitigates the risk of adverse impact from applicationchanges by localizing that risk purely to the data extracts; most of yourapplicationcodewouldbeunaffected.Iftheoperationaldatastoreisinavendorneutral format (i.e., not just a replicated copy of the external applicationdatabase), then the source of this data can even be changed to other productswith minimal impact. For example, let’s say the external application is anaccountingpackage.Usingthisstrategy,shouldyourcurrentaccountingpackagebe replacedwith a competingproduct fromanothervendor, the impactof thatchangewouldbeonlytotheextracts,nottothelion’sshareofyourapplicationcode.

This strategy, illustrated in figure4.1, alsomitigates the riskofunintendednegativeimpactonexternalapplicationuserssincethataccessisscheduledandcontrolled.Thisstrategydoesmeanthatexternalapplicationdatawillonlybeas

currentasthelatestextract.It’s important to note that there are several Extract, Transform and Load

(ETL)productson themarket that provide support for these typesof extracts.Someoftheseproductsareopensourceandfreelyavailable.ManyETLproductsuitesareverydependencyheavyand requirea significant learningcurve.Myexperience is that your extract and transformation needs have to be extensivebeforeleveragingthistypeoftoolsetiscosteffective.

Figure4.1:OperationalDataStoreStrategy

Writing to external application databases directly has considerable risk.Thisshouldbedoneonlyifthereareabsolutelynootheroptions.Itconsiderablyincreases the risk of unintended impact to users of the external application; ifyour code has a bug, the external application might not work properly.Furthermore,iftheexternalapplicationisavendedproduct,doingthismayvoidyoursupportcontract.

UtilizingWebServicesManyvendedproducts thatsupportcustominterfaceswillprovidewebservicelibraries for thispurpose.Likeany interfacechoice,webserviceshaveseveraladvantagesanddisadvantages.

Advantages of utilizing web services for applications interfaces are thefollowing:

Webservicedefinitionsareself-documentedusingWSDL.Webserviceshaveextensiveproductsupport.Webservicesprovideachangeinsulationlayer.

Webservicesareplatformneutral.WebservicescanbepublishedsecurelyovertheInternet.

Web service interfaces are popular precisely because they are platformneutral.Given the choice,most organizations like preserving the flexibility ofchoosing alternate platforms should that become necessary. In addition, toolsupportforpublishingandconsumingwebserviceshasadvancedconsiderably.Forinstance,theJavaEEspecification(JAX-WSportion)hasaddedwebserviceannotations thatmake it easier topublishwebservices.Additionally, therearenumerouswebservice frameworksavailable for Java/JavaEEaswell asotherdevelopmentplatforms.

Readers wanting code-level information on how to program web servicesusing the JAX-WS specification can see the following tutorial:http://docs.oracle.com/cd/E17802_01/webservices/webservices/docs/2.0/tutorial/doc/JAXWS.html.From an architectural perspective, it is usually advisable to segregate codeconsumingorpublishingwebservicesfromtherestofyourapplication.Thisisanapplicationofthe“singleresponsibilityprinciple”andprovidesaninsulationlayer that limits adverse effects of change on both sides. It also makesconstructingunittestseasier.Asanexample,supposeyourapplicationneedstoconsume web services offered by a document management system (DMS)product.Itypicallywouldsegregatecodeconsumingtheinterfacefromtherestoftheapplication,asillustratedinfigure4.2a.

Figure4.2a:ExampleWebServiceClientDesign

Thisdesignprovidesseveralbenefits.ChangesintheDMSproduct,suchasproductupgradesorevencompleteproductorvendorreplacements,onlyaffectthewebserviceclientimplementation;therestofyourapplicationisunaffected.The DocumentManagement interface can be mocked; unit tests for yourapplicationdonotneedaccesstotheDMStorun.

Wecan leverage thisconceptforwebserviceswepublishaswell.Suppose

that we support a reporting application and need to expose the ability to runreports to external applications. I typicallywould segregate thepublishedwebservicefromtherestoftheapplication,asillustratedinfigure4.2b.

Figure4.2b:ExampleWebServiceDesign

This design has several benefits. You are free to refactor and redesign thereporting application as desired. As long as the ReportService and associatedargumentsandWSDLspecificationarethesame,applicationsthatuseyourwebservicewillnotbeimpacted.

Additionally, providing a web service layer provides a natural insulationlayerforexternalapplicationchange.Shouldyouelecttopublishawebserviceto expose functionality to external applications; as long as that web serviceinterface remains consistent, your application can change with less risk ofadverselyimpactingapplicationsconsumingyourwebservices.

Disadvantagesofutilizingwebservicesarethefollowing:

Webservicesareoftenmoreexpensivetodevelopandmaintaincomparedtootherinterfacemethods.Webservicesarenotoptimizedforretrievinglargeamountsofdata.Webservicesmaybeunavailablewhenneeded;consumersneedanoutagestrategy.

Despite increased tool support, publishing and consumingweb services arenot cheap compared to utilizing an external application database directly.Furthermore,web services often do not have good performancewhen used toretrieve large amounts of data. For this reason, I’ve seenmany interfaces thatreaddatausingeitherthedatabasestrategymentionedaboveoraRESTservice,butwritedatausingwebserviceinterfaces.

IfyourJavaEEapplicationprogrammaticallyinitiatesprocessinginexternalapplications, you should identify those applications as actors in the use-case

analysis, as discussed in chapter 2. All specifics about the informationtransferredbetweentheJavaEEapplicationandtheexternalapplicationsshouldbethesubjectofoneormoreusecases.Forexample,thefactthatapurchasingsystem notifies the accounting system about all orders placed should be thesubjectofausecase.

UtilizingRESTfulWebServicesRESTfulwebservicesworkbyusingstructuredURLstocommunicatespecificsof an information request. For example, a RESTful web service URL likecustomeraccount/55555 might be a request for information for a specificcustomer account 55555. The return from the REST service call (which isHTTP)wouldbestructuredXML(orJSON)formatteddata.

To further illustrate, consider the following example of a purchasingapplicationusingHTTP to request information froman inventorymanagementsystem:

1. ThepurchasingapplicationissuesanHTTPrequest(usingjava.net.URL)totheinventoryapplicationrequestingcurrentinventorylevelsforanitem(e.g.,laundrydetergent).WithREST,theURLdescribesthecontentoftherequest.Forexample,theformatofaREST-stylerequestmightbe<server>/sku/<itemskunumber>(e.g.,inventorysku/14678).

2. Aservletintheinventorymanagementsystemreceivestherequest,interpretsrequestspecificsfromtheURL,andinitiatesprocessing.

3. Theinventorymanagementsystemexaminesitsdatabaseanddeterminesthequantityoftherequesteditemavailableatallwarehouses.

4. TheinventorymanagementsystemconstructsanXMLdocumentcontainingtheiteminformation.

5. TheservletintheinventorymanagementsystemreturnstheXMLdocumenttothecallerinthesamewayitwouldreturnHTMLtoabrowser.

The purchasing application receives the XML document, parses it, andcontinuesprocessing,usingtheinventoryinformationreceived.

AdvantagesofutilizingRESTfulwebservicesforapplicationsinterfacesarethefollowing:

RESTfulwebservicesprovideachangeinsulationlayer.

RESTfulwebservicesareplatformneutral.RESTfulwebservicesareofteneasiertoconsumethanwebservices.

DisadvantagesofutilizingRESTfulwebservicesarethefollowing:

Maybeunavailablewhenneeded;consumersneedanoutagestrategy.Don’thaveabuilt-indocumentationstrategy.

UtilizingMessagingServicesMessaging services are an asynchronous communication method. That is, arequest is sent, but a response may not be immediate. The Java EE providesformalsupport formessagingbyaconstructknownasMessageDrivenBeans.Essentially, the container will act as a JMS message receiver and route allmessagestoagivendestinationtoaclassthatimplementstheMessageListener(http://docs.oracle.com/javaee/1.3/api/javax/jms/MessageListener.html)interface.

ThemainadvantageofMessageservicesisthattheycanprovideguaranteeddelivery due to the fact that JMS messages are asynchronous. That is, thereceiving application may be down when the message is sent, but when thatapplication becomes available, the message will be received and processed.Consequently,applicationsconsumingamessaginginterfacedonotneedtohaveanoutagestrategy.Note thatmessages thatareneverpickedupandprocessedwilleventuallybenoticedbyendusers.

Messaging can be platform neutral, but that depends on the messagingvendor. The JMS specification utilized by JavaEEmessaging is by definitionJava-specific.However,somevendorsthatimplementtheJMSinterfaceforJavaapplicationsalsoprovideforclientsusingalternativedevelopmentplatforms.

Messagingisveryusefulinsituationswhereoneapplicationneedstonotifyanother application of a particular event. Using one of the other interfacemethods, external applications can “pull” information about that event on ascheduled basis, but that usually isn’t as timely. Advantages of utilizingmessagingservicesforapplicationinterfacesarethefollowing:

Messagingservicesprovideguaranteeddelivery.Messagingservicesareplatformneutral.MessagingserviceshaveJavaEEcontainersupport.

Disadvantagesofutilizingmessagingservicesarethefollowing:

Messagingservicesdon’thaveabuilt-indocumentationstrategy.

UtilizingEnterpriseJavaBeansEnterpriseJavaBeans(EJBs)areapureJavamethodthatcouldbeusedtocallone application from another. Advantages of utilizing EJBs for applicationinterfacesarethefollowing:

EJBdefinitionsareself-documentedusingthepublishedJavainterface.EJBshaveextensiveproductsupport.EJBsprovideachangeinsulationlayer.

DisadvantagesofutilizingEJBsforapplicationinterfacesarethefollowing:

EJBsarerestrictedtoJava-basedclients.EJBsarenoteasilysecured.EJBsmaybeunavailablewhenneeded;consumersneedanoutagestrategy.

While the JavaEE specification has belatedlymadeEnterprise JavaBeans(EJBs)easytopublish,andtoolingsupportisreadilyavailabletoconsumethem,web services are more popular. Web services provide the same functionalfeaturesthatEJBsdowithoutlimitingconsumerstoJava-basedapplications.

COMMONMISTAKESUsing databases and file systems as “message brokers.” This error-pronestrategyconsistsofwritingarowinadatabasetable(orafileinafilesystem)with the contents of amessage. The second part to the strategy is writing anagentthat“polls”thedatabase(orfilesystem)fornewmessagestoarrive,readsandprocessesthemessagecontent,andthendeletestheroworfile.

Inessence,thisstrategyisakintowritingyourownmessagingsystem.Itistypicallyafrequentsourceofbugs.Whyreinventthewheel?Chooseoneoftheexisting forms of communication and concentrate on business logic, not low-levelcommunicationprogramming.

Usinganasynchronouscommunicationmethod,suchasmessaging,whena

responseisrequired.Withthisstrategy,yourapplicationsendsanasynchronousmessage to another application and waits for a return message from thatapplication.

Usingasynchronouscommunicationwhenresponsesarerequiredputsyouinthepositionofprogramminganalgorithmtowaitforaresponse.Howlongdoyouwait?Ifyouwaittoolong,youcouldbeholdingupauser.Ifyoudon’twaitlongenough,youcouldmistakenly report an error.This is akin to twopeopletryingtofindeachotherinthedarkinanextremelyloudroom.Ifaresponseisrequired,useasynchronouscommunicationmethod.

If the application initiating the message doesn’t require a response, usingasynchronouscommunicationmethodsarelessvulnerabletounplannedoutagesas the sender won’t experience an error if the receiving application isn’tcurrentlyavailable.Thereceivingapplicationwillmerelyconsumethemessagewhen it comes back online. As asynchronous messaging requires messagingsoftware,usingasynchronouscommunicationaddscomponentsandcomplexitytotheapplication.LestIleaveyouwiththeimpressionthatusingasynchronousmessagingisdangerous,messagingtechnologiesaremature,robust,andstable.

Not considering production environment requirements. For organizationsthat don’t standardize load balancing options, communication protocols, andsecuritymethods,youwillneedtoinvestigatewhatexternalapplicationplanstouseandaccommodatethoseplansintheinterfacedesign.Fororganizationsthatstandardizesecurityconcernsandhardwareplatformsacrosstheenterprise,thisinformationmight already be known.Oneway tomitigate this risk is to do asmall test implementationof theplannedcommunicationmethodupfront.Thatwayyou’llhavemoretimetoreactifyouneedtomodifyyourdesign.

DETERMININGADATASTRUCTUREDocument all data passed to an external application. The communicationstructureorformat,alongwiththeconditionsthatdictatetransmission,arepartofyourcontractwiththeexternalsystemdevelopers.Thedatastructureshouldbedocumentedinwriting.

Use simple structured formats for interfaces to legacy platforms such asXMLorCSV.XMLcanbeaheadachefordevelopersusinglegacyplatformsifyourcompanywon’tbuyanXMLparser.Opensourceparsersandother toolsarenotavailableforCOBOLorPL/Iatthetimeofthiswriting.Thiswouldbea

valuableopensourceproject.Whentheexternalapplicationisa legacysystemandtheclientdoesn’tbuyXMLtoolstoassist,customformatsarecommonoutof practical necessity. Custom formats can have a keyword-type organization(like XML) or some type of positional organization. COBOL lends itself tofixed-lengthstringsusingapositionalformat.

You need to develop a DTD or schema, or otherwise document the XMLdocument formats and tags with allowed values. Leaving this communicationverbal is a recipe for disappointment and countless project delays. Chapter 7includesmaterialtohelpyoudesignXMLdocuments.

CSVformatsappearwidelysupportedbymanypurchasedsoftwareproducts.However, although writing a specification for the CSV format has beenattempted, there isn’t formal agreement on what delimiters are permitted andwhat escape characters are supported for strings. For these reasons, I trendtowardusingXMLifit’sanoption.

It is not necessary to validate XML documents for external interfaces.DevelopingaDTDtodescribeadocumentformatdoesnotmeanthatyouhaveto “validate” the document when it’s parsed. Validation works well fordocumentsthatweredirectlywrittenbypeopleandthusmorelikelytocontainerrors. Application interfaces aremechanical. Aside from initial development,the probability of receiving a malformed XML document that wasprogrammaticallygeneratedfromanotherapplicationisverylow.Giventhis,thebenefitsofvalidationdon’tusuallyoutweighitsperformancecosts.

Avoid sending serialized Java objects as message content. This effectivelynegatesthebenefitsofloosecouplingbymakingbothapplicationsdependentonthe same classes. If a change ismade to one of the objects referenced by theserialized class, the change would have to be deployed to both applicationssimultaneously. Further, serialization problems can occur if one of theapplicationsupgradesitsJavaVirtualMachine(JVM).Serializedobjectscannotbe visually inspected to determine content; they must be programmaticallyprocessed.TheyalsolimitcommunicationtoJavaapplications.

ERROR-HANDLINGREQUIREMENTSError-handling requirements need to be discussed, documented, and agreed tojust as thoroughly as data formats do. Bad error handling will lead to highmaintenancecosts.

ErrorNotificationProceduresAll external application interfaces should have error notificationprocedures. Some organizations provide centralized operations personnelresponsible for notifying application support personnel of errors. This is oftenachieved through some type of console message. It’s not uncommon for theconsole to be monitored 24x7x365. It’s normal for organizations with thiscapabilitytoprovidesomewaytoprogrammaticallygenerateaconsolemessagethatsomeonetakesactionon.

Use mechanical error notification. In companies that haven’t establishedenterprise-wideerrornotificationprocedures,Itypicallyincludesometypeofe-mailnotificationforseveresystemerrors.Merelywritingerrorstoalogassumesthatsomeonewilllookatthem.Messageswrittentothelogoftengounnoticed.As most alphanumeric pagers accept message via e-mail, it’s easy to includepagernotificationforsevereerrors.Thisshouldbeusedwithcautionforobviousreasons.

Don’tbeafraidtobeverbosewhenloggingforerrors.Myphilosophyisthattheerrorlogshouldcontainasmuchinformationaspossible.Whilesomeofitmightnotbeusefulforaparticularproblem,it’sbettertohavetoomuchratherthan too little when it comes to information. If logging is successful, a largepercentageoferrorsshouldbediagnosablejustfromtheerrormessagewithoutfurtherneedtoreproducetheproblem.

At some companies, commercial tool support is available to help withlogging. BMC Patrol, EcoTools, and Tivoli are commercial networkmanagement toolsets that are often used tomonitor the enterprise.OpenNMS(http://www.opennms.org)andNagios(http://www.nagios.org/)areopensourcealternativesfornetworkmanagement.

RetryProceduresOnce initial development is complete, most errors with interfaces haveenvironmental causes. Examples include someone recycling the database ormessagingsoftware,someonetrippingoveranetworkcord,andaserverwithafullfilesystem.Inmostcases, theerror iseventuallyfixedandtheapplicationinterfaceresumesproperfunction.

However, withmost applications, some type of recovery or retransmissionprocedure must be performed for the transmissions that failed. For example,messages recording customer purchases from the ordering applicationmust be

resenttokeepaccountingrecordsaccurate.

Make retry procedures mechanical. For transmissions that a user isn’tphysicallywaiting for, Ioftenput a scheme for automatic retry logic inplace.Environmental problems occur often enough in most companies to warrantincluding selective retry logic to recover fromoutagesmore quickly andwithlesseffort.Theobjectiveoftheretrymechanismistoautomaticallyrecoverfromatemporaryoutagewithoutmanualinterventionbyanapplicationadministrator.

The potential for complexity lies in discriminating between temporaryoutagesanderrorsthatwon’tmagicallygoawayovertime.It’spossibletotakeashotgun approach and assume that all errors occur as a result of a temporaryoutage,andthereforealwaysinitiateretrylogic.Thedangeristhattheretrylogicintroduces an infinite loop for any situation other than a temporary outage.Consequently,youshouldusethisapproachwithcare.

All mechanical retry logic should have limits. It’s important not to retryforever,essentiallycreatinganinfiniteloop.Chooseasensibleretryintervalandnumberofretryattempts.It’salsowisetomaketheselimitsconfigurablesotheycanbeeasilyadjusted.Retryattemptsshouldalsobeloggedorpossiblyfollowyour mechanical notification procedure. Upon receiving notification of theretries, an application administratormight realize that corrective action shouldbetaken.

EXTERNALINTERFACEGUIDELINESManyJavaEEapplicationscommunicatewithexternalsystems,someofwhichmaynotbeJavaapplications.Asanapplicationarchitect,you’llprobablyhavean opportunity to facilitate design and implementation of external interfaces.Overtheyears,I’veadoptedseveraltechniquesforcreatingsuccessfulexternalinterfaces.

Record every request or transmission from or to an external application.This should be the first task in any external interface. Be sure to log thisinformation so that you know the time (and node if you’re in a clusteredenvironment). If there’s a problem with work you initiated in an externalapplication, you’ll want to be able to tell those developers exactly what callstheymade andwhen. If there’s a problem processing a call from an externalapplication,you’llwantenoughinformationtoreplicateitandfixanyproblemsquickly.

This documentation practice helps prevent you or any member of thedevelopmentteamfrombeingblamedforthemistakesofothers.Withoutfacts,anyonecanmakeaccusations,andintoomanycorporationsyou’reguiltyuntilproven innocent. Having a transmission log will make it easier to determinewhichapplicationhasaproblem.

Createawayforanapplicationadministratortoresubmitaworkrequestfrom an external application. When your application experiences anenvironmental problem and you’re able to fix it, the application administratorshouldbe able to resubmit thework that failed.This limits the impacton endusers and limits the number of people (and thus the time) needed to fix aproblem.Sometimes, resubmission isn’tpossibleorapplicable.But itcansaveyoutimeforactivitiesthataremorefunthanmaintenance.

As an example, one of the applications I supported provided scheduledreporting capabilities. An application administrator could resubmit any reportthatwasn’tbeingdeliveredtoabrowserbyanadministrativeweb-basedutility.

Collect the identity of the transmitter. Part of every transmission should beinformation that indicates the identity of the caller.This ismeant as away toreduceyourmaintenance time, not as a securitymechanism. In the caseof aninappropriatecall,youwanttobeabletoquicklynotifytheapplicationmakingit.Ifyoudon’tknowwhereit’scomingfrom,findingitandgettingitfixedtakeslonger.

Developamechanicalwayto“push”errorstothetransmitter. If thereisaproblem processing a request made by an external application, administratorsfrom that application need to be notified. If the interface has a tight coupling(e.g., session bean, RMI service), all you have to do is throw an exception.Whatevermechanism theexternalapplicationuses forerrorprocessingwillbeabletohandletheerror.

Iftheinterfacehasaloosecoupling(e.g.,usesmessagingtechnologies),youneedtoconstructawaytomechanicallynotifyadministratorsfromtheexternalapplicationof theerror.Mostoften, I’veseene-mailusedasaneffectiveerrornotificationchannelforthesecases.Asmostalphanumericpagesaccepte-mails,pagingisapossibility.However,Iwouldthoroughlytestyourerrorprocessingbeforehookingituptoapager.

Ensure thatyouadequately testerror-handling logic.Oftendeveloperswillneglect the testing of error handling. Errors in error-handling logic can easily

masktheunderlyingproblem,makingproductionsupportmuchmoredifficult.

SECTIONII

DESIGNINGJAVAEEAPPLICATIONS

The application architect typically leads and facilitates all application designactivities.Inthissection,youwilllearnhowto:

Documentapplicationdesignswithobjectmodelssootherdevelopmentstaffcaneasilyunderstandthedesign.UnderstandsoftwarelayeringconceptsandhowtousethemtoorganizeJ2EEapplicationsintosmallerandmoremanageablesections.Applycommondesignpatternsateachsoftwarelayer.Documentapplicationstoragerequirementsusingdata-modelingtechniques.DesignXMLdocumentformats.Refineprojectestimatesafterthedesignphase.

CHAPTER5

ALAYEREDAPPROACHTOJAVAEEDESIGN

Applicationarchitects,bydefinition,mustsupplyapplicationdeveloperswithanoveralldesign.Itisimportantthatdevelopersunderstandtheoveralldesignsotheycanmakelowerlevelcodingdecisions;architectscan’texpectdeveloperstofollow a design they don’t understand. Furthermore, if developers havedisagreementswiththeintendeddesign,it’sbesttoresolvethosedisagreementsbeforetoomuchcodeiswritten.

Althoughextensivedocumentationisfrowneduponthesedaysasmanytrendtoward agilemethodologies, some amount of designdocumentation is needed.The larger the effort (and the number of developers), themore extensive thisdocumentationneedstobe.Havingsomeamountofdocumentationallowsyoutomore quickly and easily involve additional developers in the effort, shouldthatbeneeded.

ThischapterpresentsandexplainsageneralapproachtodesigningJavaEEapplications.Thisdiscussionisnecessarybackgroundtothenextchapter,whichoffers tips and techniques for transforming the use-case analysis described inprevious chapters into a concrete design. It is a general approach that can beappliedtoallbusinessapplications.

ThefactthatmyapproachtoallJavaEEbusinessapplicationsisconsistentallowsme tominimize the design documentation needed for each applicationbuilt. Since developers who have worked with me on previous projects arealreadyfamiliarwiththeconcept,there’slesstimespentgettingdevelopersuptospeedonmydesignsortransferringdevelopersbetweendevelopmentefforts.Italsominimizesthenumberofsupportdevelopersneededforeachapplication.

Object models are the most popular mechanism for documenting Java EEapplication designs. The application architect is typically responsible forfacilitating creation of object models for the most complex portions of theapplicationtobedeveloped.Forthoseusingagilemethodologieswithveryshort

iterations(e.g.,twoweeksperiteration),thisisashortexerciseatthestartoftheiteration.

In addition to object models for the most complex portions of thedevelopment effort, I often have illustrations that describe major businessprocessflows.Igenerallyuseswim-lanediagramsforthispurpose.Thischapterwillprovideamorein-depthdescriptionoftheseandasample.

JavaEE application design is a vast topic. Entire books have beenwrittenaboutdesign techniques,designpatterns,andobjectmodelingwithUML.Andlikemostlargeandcomplicatedmethodologies,UMLisonlypartiallyappliedinbusinessapplications.Thus,although Idon’twant todiscourage learning, Idotake a streamlined approach to the topic in this chapter. For instance, of thehundredsofdesignpatternsthathavebeenidentifiedandcataloged,thischapterfocusesonthehandfulofpatternsmostcommonlyusedinbusinessapplicationstoday.

OVERVIEWOFTHELAYERINGCONCEPTAcommon framework for JavaEEapplications is software layering, inwhicheach layerprovides functionality forone sectionof the system.The layers areorganized to provide support and base functionality for other layers. Forexample, the data access layer provides a set of services to read and writeapplicationdata.An inventorymanagementapplicationneedsservices thatcanreadinformationaboutspecificitemsandwarehouses.

Layeringisnotanewconcept;operatingsystemsandnetworkprotocolshavebeen using it for years. For instance, anyone who’s worked with networks isfamiliarwithtelnet,FTP,andInternetbrowsers.AlltheseservicesdependonaTCP/IP networking layer. As long as the interface to TCP/IP services staysconstant,youcanmakenetworksoftwareadvanceswithin theTCPframeworkwithout affecting telnet, FTP, or your web-browsing capability. Typically, theTCP/IPlayerrequirestheservicesofadevicelayer,whichunderstandshowtocommunicatewithanEthernetcard.

Business applications can make strategic use of the same concept. Forexample,it’scommontomakedataaccessaseparateportionofanapplicationinordertomakeiteasiertoconsolidatedataaccesslogicusedinmultipleportionsofanapplication.Forinstance,acustomerlookupbyIDmightbeusedinseveralportionsof anapplication.Withdata access separatedandconsolidated inonelayer,existingcodeiseasytorecognizeandreuse.Inaddition,shouldyourdata

accessmethodchangeinsomeway(e.g.,youswitchyourunderlyingdatabasefromMySqltoOracle),thewaytheapplicationphysicallyreadsandwritesdatamaychangewithoutaffectingapplicationprocessingorbusinesslogic.

To continue the inventory management example, suppose the data accesslayerhadamethodtolookuptheinformationforaninventoryitemgivenaUPCcode. Suppose that other parts of the application use this method wheninformationaboutitemsisneeded(e.g.,acustomerviewingthatitemonawebpage or an inventory analyst ordering stock for that item). As long as themethodsforaccessingiteminformationremainthesame,youshouldbeabletoreorganizehowyoucanstore informationabout itemsandwarehouseswithoutaffectingtherestoftheapplication.

In essence, a layered approachmitigates the risk of technical evolution. Ifyouuse thisconcept toseparateyourdeploymentmechanics (e.g., JavaServerFacesorStruts),youcanaddnewdeploymentswithoutchangingyourbusinesslogic or data access layer—for example, if you decide to expose applicationfunctionality via web services. If your application effectively separates yourbusiness logicanddataaccess logic fromthe restofyourapplication,youcanfreely add a web services deployment without having to change the entireapplication. Table 5.1 lists common software layers used in Java EEapplications.

Table5.1:TypicalSoftwareLayersinJavaEEApplications

Layer Role

Dataaccessobjectlayer

Managereading,writing,updating,anddeletingstoreddata.CommonlycontainsJDBCcode,butcouldalsobeusedforXMLdocumentandfilestoragemanipulation.

Businesslogiclayer

Managesbusinessprocessingrulesandlogic.

Entityobjectslayer

Lightweightstructuresthataremappeddirectlytorelationaldatabasetables.

Valueobjectslayer

Lightweightstructuresthatfacilitatedisplayofsummarizedbusinessinformation.

Deploymentlayer

Publishesbusinessobjectcapabilities.

Presentationlayer

Controlsdisplaytotheenduser.

Architecturalcomponentlayer

Genericapplicationutilities.Often,theseobjectsaregoodcandidatesforenterprise-wideuse.

Softwarelayeringimplementsanarchitecturalconceptcalledtheseparationof concerns. The separation of concerns principle states that softwarecomponents shouldhavea single focusandbeconcernedwithonlywhat theyneed to accomplish andnothingmore.Furthermore, the focusof one softwarecomponentshouldnotoverlapwiththatofanothercomponent.Thebasicideaofthis principle is to simplify software development by breaking large complexproblems intomultiple smaller and therefore simpler problems. This principlealsoincentsreuse.Moreinformationontheseparationofconcernsprinciplecanbe found here: http://aspiringcraftsman.com/2008/01/03/art-of-separation-of-concerns/.Caseswherethisprincipleisviolatedarecommonlyreferredtoasaleakageofconcerns.

Typically,callingpatternsbetweensoftwarelayersaretightlycontrolled.Anyclassinasoftwarelayercancallanyotherclassinthesamelayer.Forexample,classes in the data access layer can leverage any other data access class.However, data access layer classes do not call business logic layer orpresentation layerclassesas thoseclassesaren’tdirectly involvedwithreadingorwritingstoreddata.Businesslogiclayerclassescancallotherbusinesslogiclayerclassesaswell asdataaccessclasseswhen theyneed to initiate readsorwritesforstoreddata.Business logic layerclassesdonot issueSQLor initiateanyreadingorwritingofstoreddatathemselves;thatactivityisdelegatedtothedataaccesslayer.Figure5.1illustratestypicalsoftwarelayeringcallingpatternsforJavaEEapplications.

Figure5.1:SoftwareLayeringCallingForJavaEEApplications

Note that entity and value object classes are used by all layers as they areusedtopassinformationbetweenothersoftwarelayers.

When this boils down to code, I usually implement the layers as separatepackages.Here’sanexamplepackagestructure:

com.jmu.app.dao Dataaccessobjectlayer

com.jmu.app Businesslogiclayer

com.jmu.app.entity Entityobjects

com.jmu.app.vo Valueobjects

com.jmu.app.ui Presentationlayer

com.jmu.app.util Architecturalcomponentlayer

com.jmu.app.services Deploymentlayer/webservices

Iuse theabbreviation jmufor“justmadeup.”Also,you’llwant to replacetheappabbreviationwithameaningfulapplicationname.

It’simportanttonotethattheonlylayerthatdirectlyutilizesthedataaccesslayeristhebusinessobjectlayer.OnequestionIcommonlyhearis,whynotcallthe data access object layer directly from the presentation layer? Althoughcallingthedataaccessobjectlayerdirectlycansavesomecodebyeliminatingacouple of layers, itmeans placing any business logic either in the data accessobjectlayerorthepresentationlayer,whichmakesthoselayersmorecomplex.Software layeringworkson thepremise that it’s easier to solvemultiple smallproblemsthanfewerlargeones.Experiencehastaughtmetwolessons:

Shouldthedatalayerbemodified,fewertouchpointswillbeaffectedastheyareallconsolidatedinthebusinesslogiclayer.Thereistremendousvalueinconsistency.

Thereisvalueinconsistencyformaintenancepurposes.Forinstance,ifsomeJSPscalldataaccessobjectsdirectlywhileothersworkthroughbusinessobjectsand others use deployment wrappers, to make a change to code you’reunfamiliar with, you have to do an audit of the whole action sequence. Thisdefeatsthepurposeofseparationofconcernsandsoftwarelayering.

I’ve had the privilege of utilizing a consistent architecture across anenterprise for oneofmy clients.At that particular client site,we typically areabletosupportadozenapplicationswith2.5supportdeveloperresources.Atallother client sites I’m aware of, it takes multiple developers to support mostapplications.Theconsistencyofthearchitectureisoneofthelargestreasonsmyclientgetssuchgooddeveloperefficiency.

DATAACCESSOBJECTLAYERDataaccessobjects (DAOs)manageaccess topersistent storageofsome type.Usually,thestorageusedisarelationaldatabase,butDAOscanmanageaccessto NoSQL databases, files, XML documents, and other types of persistentstorageaswell.

NoSQL(shortforNotOnlySQL)databasesaregainingpopularity.NoSQLisa term that describes databases that don’t use SQL as a primary syntax forinteractingwiththem.Therearemanyproductswithinthe“NoSQL”umbrella.In fact, there are several categories of NoSQL databases, such as documentstores,keyvaluestores,graphdatabases,etc.NoSQLdatabasesvarywidelyandhavedrasticallydifferentstrengthsandweaknesses.Becauseofthat,describingthe various advantages and disadvantages of the various products with a“NoSQL”designationwouldrequireabookinitself.

Therehavebeenattempts,however, togeneralizethemorepopularNoSQLdatabase products and provide a general overview of their strengths andweaknesses. The best synopsis that I have found can be viewed here:http://kkovacs.eu/cassandra-vs-mongodb-vs-couchdb-vs-redis. As a very broadgeneralization,aNoSQLdatabaseisapossiblecandidateforanydatastorethatdoesn’t easily fit the relational databasemodel and forwhich the queries youplan to execute against the data store are known and well-defined. Logging

seems to be a popular use for NoSQL databases. NoSQL also appears to becommonly used for Content Management Systems (CMS) applications.However, at the time of this writing, relational database access stillpredominates.Assuch,relationaldatabaseaccesswillhaveamuchlargerfocusinthisbook.

Theprimaryreasontoseparatedataaccessfromtherestoftheapplicationisthat it’s easier to switch data sources and it’s easier to share DAOs betweenapplications.Furthermore, in caseswhere there aremultiple applicationsusingthesamedatabase,itmaybepossibletoconsolidatedataaccesslayercodeandleveragethesameaccesscodeacrossmultipleJavaEEapplications.

A couple of patterns for data access objects are the most common. ThesimplestpatternhaseachpersistentobjectrepresentedasaDAO.Icallthisthesimplifieddataaccesspattern.Themorecomplex,butmoreflexible,patternincommonuseisafactory-basedpattern.Infact,it’scalledthedataaccessobjectpattern.I’lldefineeachpatternlaterinthesection.

For convenience, I separate DAO objects in the package hierarchy (e.g.,com.acme.appname.data or com.acme.appname.dao). I only mention thisbecausesomemodelingtools(e.g.,RationalRose)encourageyoutodecideyourpackagestructureatmodelingtime.SomedevelopersalsoaddaDAOsuffixtodata access object names; for example, a customer DAO might be namedCustomerDAO.

ChoosingaDatabasePersistenceMethodThequestionofwhichpersistencemethodisbestisthesubjectofconsiderabledisagreementanddebate.AlthoughtheJavaEEspecificationprovidesforentitybeans, other popular forms of database persistence exist.The degree towhichdeveloperstakesidesinthedebateisakintoadiscussionofreligionorpolitics;the debate is not entirely rational. I’ll take you through my thoughts on thedifferent options, what I see in the marketplace, and what I prefer to use.However,themodelingconceptsinthischapterareapplicabletoallpersistencemethods.

Whenbeginningobject-modelingactivities,youcanidentifyaDAOwithoutchoosingthepersistencemethodyou’lluseatimplementation.Forinstance,theDAOcouldbea custom-coded JDBCclass, a classusing the JavaPersistenceAPI (JPA) (e.g., Hibernate), or an object utilizing an object-relational (O/R)mappingtoolsuchasIbatis.JavaEEapplicationsarecompatiblewithallthesepersistencemethods.

Inmakingadecision,Ifirstconsiderwhatneedstohappenatthedataaccessobjects layer. I then grade each persistence method according to how well itachievesthegoals,usingthefollowingratingsystem:

High(bestrating):Getshighmarkstowardachievingthestatedgoal.Medium(middlerating):Moderatelyachievesthestatedgoal.Low(lowestrating):Doesn’tachievethestatedgoalverywell.

Table 5.2 lists the goals and ratings of several data persistence methods.Followingthetableareexplanationsofmyreasoningindeterminingtheratings.Iconsiderthefirstfourgoalslistedinthetabletobethemostimportanttothemajorityofmyclients.

Table5.2:RatingsofDataPersistenceMethods

Goal JDBC JPA O/RTool

Minimizelearningcurve High Medium Medium

Minimizecodeandconfigurationfileswrittenandmaintained Low Medium Medium

Maximizeabilitytotune High Low Low

Minimizedeploymenteffort High Medium Medium

Maximizecodeportability Medium High High

Minimizevendorreliance High High Low

Minimizethelearningcurve.BecauseJDBCwasthefirstpersistenceAPIfordatabases,itisthemostfamiliartomost,ifnotall,Javadevelopersandthushasthelowestlearningcurve.TousetheJPAoranORMtoolset,developersneedtounderstand JDBC in addition to the technology they are directly using. Thereasonforthisis:whenerrorscomeup,itisnecessarytounderstandwhatyourJPAorORMimplementationisdoingtodiagnosetheerror.

Minimizecodeandconfigurationfileswrittenandmaintained.Peoplehaveatendencytoconsiderthenumberoflinesofcodeonlywhenevaluatingeaseofdevelopment. I view any configuration file (e.g., an annotation or XMLconfiguration file) as code with a different syntax. JPA implementations andmost O/R toolsets I’m familiar with save some percentage of code in mostsituations.

Maximizetheabilitytotune.Becauseit’s thelowest levelAPIandclosest tothe database, JDBC provides unfettered ability to tune database SQL. Everyother choice relies on a product to generate the SQLused. For instance,mostJPA implementations and object-relational mapping tools generate the SQLexecuted;it’susuallyhardertotunewithoutdirectcontroloftheSQLused.

Minimize the deployment effort. Deployment hassles negatively impactdevelopmentandmaintenancetime.Inthiscase,allproductchoicesappeartoberoughlyequivalentintermsofeffortneededtoredeploychanges.

Maximize code portability. Being able to port data access code from onedatabase toanother isaconsiderationforsomeapplications. In thissense,JPAimplementations can offer the best opportunity forwriting truly portable codethat can run using any of the popular relational databases. Formany businessapplications,needingtoswitchtheunderlyingdatabasevendorisarareevent.Inwhichcase,thiscriterionshouldreceivelessweight.

Minimize vendor reliance. You need to reduce your dependence on vendorsthat provide Java EE container services, JDBC drivers, JPA implementations,andO/Rtoolsets.This isdesirable fromabusinessstandpointshouldavendorfail or change its cost structure. You can change vendors for JDBC driverseasily;I’vedoneitmanytimeswithmultipledatabasevendors.SwitchingJDBCvendors is usually just a jar file change along with a container configurationchange.MostapplicationsdonotuseJDBCvendor-specificclassesandwillnotrequirechangeshouldyouswitchvendors.

Changingcontainervendorsismoderatelyeasy.Youdohavethepossibilityofperformance-tuningissues,particularlywithJPAvendors.WithO/Rtoolsets,application code directly uses vendor (or vendor-generated) classes. SwitchingO/Rtoolsetsrequiressignificantdevelopmentinmostcases.

I think about the use of software toolsets in the same way an economistthinksaboutmarketefficiency.Financialanalystsandeconomistshaveatheorythat financialmarkets are efficient. That is, when a new piece of informationbecomes public, the stock prices of all companies related to that informationchangeaccordinglyovertime.Forexample,whentheEnronandUnitedAirlinesbankruptcies became publicly known, the news had profound effects on theirstockprices.

Whennewsoftwareparadigmsare introduced, if theyprovidebenefits thatexceedtheircosts,overtimedeveloperswillswitchtothem.Thetimeframein

which this happens for programming paradigms is much slower than that forfinancialmarkets,but thegeneralconceptismuchthesame.WhenIwrotethefirsteditionofthisbook,the“market”consensusregardingdatabasepersistenceappearedtobefavoringnativeJDBC.However,searchenginekeywordinterestin Hibernate (a JPA implementer) has interest in JDBC. The inference is thatdevelopersaretrendingtowardJPAimplementationssuchasHibernate.It’salsopossible to use job posting data as a proxy formarket consensus; job postingdatashowthatemployerinterestinHibernatehassurpassedthatofJDBC.Thesearch engine keyword data I refer to comes from Google Trends and ispresentedinfigure5.2.JobpostingdataIrefertocan’tbeincludedbecauseoflicensingrestrictions.

Figure5.2:SearchEngineKeywordStatisticswithPersistenceTechnologyTerms

Source:GoogleTrendstakenonNovember17,2013.

SimplifiedDataAccessPatternOf the two patterns for data access objects that aremost common, this is thesimplest. In this pattern, there is a one-to-one correspondence between thephysical storage construct (e.g., relational database table, XML document, orfile) and the DAO that manages it. For example, you might haveCUSTOMER_DAO manage access to a CUSTOMER table in a relationaldatabase.Althoughyouhaven’tidentifiedmethodsyet,youcanimaginethatthisclass will have methods to search and return information on one or more

customers using search criteria as arguments. Itmight havemethods to insert,update,anddeletecustomersaswell.

Theadvantageofthispatternisthatit’ssimple.Itschiefdisadvantageisthatit’softenspecifictoonedatasourcetype.ThecodeinvolvedinmanipulatinganXML document is quite different from the JDBC and SQL required to usedatabase tables. Switching the data source typewould be amajor overhaul tomostmethodsintheclass.

This pattern is usable nomatterwhat database persistencemechanism youchoose.YourdatapersistencemethodchoicemerelydictateshowDAOclassesareconstructedinternally.Figure5.3illustratesanobjectmodelforthispattern.

Figure5.3:ASimplifiedDataAccessPattern

SupportingMultipleDatabasesFor an application that supports multiple types of databases, the data accessobjectpattern,whichisfactorybased,isquitecommon.ThispatternimplementstheDAOasaninterface.Afactoryisrequiredtoproduceobjectsthatimplement

thisinterface.Inaddition,youwillhaveanimplementationofthisinterfaceforeachtypeofdatasource.Thefactoryissmartenoughtoknowhowtoinstantiateallimplementations.Figure5.3illustratesanobjectmodelforthispattern.

Figure5.4:DataAccessObjectPattern

For example, consider a customer DAO implementation. It would have aCustomerDAOinterfacethatwouldspecifyavarietyofsearchmethodsaswellas an update, delete, and insert method. It would also have a customer DAOfactory (CustomerDAOFactory) responsible for providing a DAO for theapplication to use. It might also have an implementation for all relationaldatabases it supports (e.g., CustomerDAOOracleImpl,CustomerDAOSybaseImpl, CustomerDAOMySQLImpl, etc.). The businessobjectcodewoulduse theCustomerDAO interfaceexclusively so it coulduseanyoneoftheimplementations.

Anotherreasonyoumightneedthislevelofconfigurationinthedataaccesslayer is for unit testing purposes. When unit testing the business logic layer(whichisthechiefconsumerofthedataaccesslayer),itisoftenusefultostubout the data access layer for business layer unit tests. This eliminates thedependencyonaspecificdatabase.

ConsiderusinganInversionofControl(IOC)productinplaceofmanuallycodingtheobject factories.Currentpopular IOCimplementationsareSpring,Google Guice, and Pico. These products eliminate the need to code factory

classes,butintroducesomelevelofconfigurationandcomplexity.

The data access object pattern is overkill if you don’t foresee a need tosupportmultipledatabase vendors anddonotplan tomaintainunit testsfor the business layer. Few business applications need to be able to supportmultiple databases.Whilemost developers employ some level of unit testing,manydonot practice test drivendevelopment rigorously as it ismore code tomaintain. If yourorganization isdiligent aboutwriting and runningautomatedunit tests, then you likely need to use the data access object pattern. If yourorganizationdoesn’tsupportthisleveloftesting,thenyougetnobenefitfortheadditionalcomplexitythispatternrequires.Softwarevendorsaremorelikelytoneed this pattern than business application developers. I discuss it at lengthbecauseithasanunqualifiedrecommendationinmanytexts.

ENTITYOBJECTLAYERMostapplicationsuserelationaldatabasesforstorage.Entityclasseshaveaone-to-one mapping to one of the application’s relational database tables. Forexample,ifyouhaveaCustomertable,therewillalsobeaCustomerEntityclassthat represents that table inJava.Thatclasswillhavefields thatcorrespond tocolumnsonthattable.Forallpracticalpurposes,aninstanceofCustomerEntityrepresents a row in the Customer table. For all practical purposes, the entityobjectlayerrepresentsa“Java”versionoftheapplication’srelationaldatabase.

Data access classes in one sense are factories for entity classes. They userelationaldatabasedataas“input”andproduceoneormoreinstancesofentityclassesasoutput.Theyalso translatedata inentityclassesandpersist it to theapplicationsdatabase.

Typically,entityclassesareseparatedintoadifferentpackagestructure(e.g.,com.acme.appname.entity). In addition, it’s often helpful to use a namingconventionforentityclassessothatthefactthataclassisanentityclasscanbeeasily identified. Often, I use an “Entity” suffix for entity classes (e.g.,AccountEntity). If thedatabasedesignadheres to3rdnormal form(whichwillbedescribedinaseparatechapter),entityclassesderivedfromthatdesignwillclosely match what would have been identified from an object modelingperspective.Forexample,the“customer”and“account”tablesdiscussedearlierare logical candidates for Java classes in an object modeling exercise. Everyapplicationhasdataitemsthatlogicallybelongandtypicallyareusedtogether.

Typically,entityclasseshaveaccessorandmutatormethods,butusuallylittle

else.Theyaretypicallyreferencedinallotherapplicationlayers.

VALUEOBJECTLAYERIn addition to entity classes,which represent data thatwill be saved and laterretrieved, every application has transient data items that logically belong, andtypicallyareused,together.Transientdataisdatathatexistsonlytofacilitateaspecific body of work, but isn’t directly saved. Value object (VO) classesrepresent this data. For example, value objects might be used to representaggregatesales informationforuserdisplay(e.g.,SalesDisplayVO).Aggregatesalesinformationisn’toftenstoreddirectly,butsummarizedfromdetailedsalesdatawhenneededfordisplayorreporting.

Thereissomelabelingconfusionsurroundingthetopicofvalueobjects.Mydefinition of “value object” is very close to aDataTransferObject (DTO).Adefinition of a DTO can be found here:http://martinfowler.com/eaaCatalog/dataTransferObject.html.Foryears,theJavaEE community promoted use of DTOs as the preferred way to transmit databetween session beans (EJBs) and their clients (hence theword transfer in itstitle). As use of the termDTO implied use of enterprise session beans,manybeganusingtheterm“valueobject”toavoidthatimplication.Itshouldbesaidthat the term value object has a different meaning in C++ circles. In thosecircles,valueobjectsdescribeonevalueinameaningfulway(e.g.,money,date,etc.).

IntheearlydaysofJavaEE,enterprisebeans(EJB)weremuchmorewidelyused than they are today. With enterprise beans, value objects were used tooptimizenetworktransmissionsbetweenthebeansthemselvesandtheircallers.AsEJBusehasdeclined,mostapplicationsdon’tneedthatlevelofdistribution,sousingvalueobjectclassesforthispurposeislessrelevant.

It’sprogrammaticallyconvenienttotreatthislogicalgroupofdataitemsasaseparateobject.Thistypeofobjectiscommonlyknownasavalueobject(VO),althoughsometextsrefertoitasadatatransferobject.IfJavahada“structure”construct,asC/C++andmanyotherlanguagesdo,aVOwouldbeastructure.

Forexample,youcouldcombinevariouspiecesof information fora reporttemplate into a VO.Methods needing a report template argument could thenaccept the ReportTemplateVO instead of individual arguments for allcomponentsofthestructure.

Typically,aVOhasaccessorsandmutatorsbutlittleelse.AndusuallyaVO

implements java.io.Serializable so it can be transmitted to remote applicationclientsorserializedinsession.JavaEEcontainersandRMIservicesserializethecontent of Java classes before transmitting them to a remote machine. Acommon convention is to give value object names a VO suffix, as inCustomerVO.

CommonPatternsThevalueobjectoriginatesfromaformallydefinedpattern.Insometexts,thispatterniscalledthevalueobjectpattern(Alur,Crupi,andMalks,2001).TheVOpattern enhances EJB performance but is useful in communication among alllayersoftheapplication.

Youcancombine theVOpatternwith thecompositepattern,which isusedwhen something contains other things. For instance, a report template oftencontains multiple parameters. Using the composite pattern, theReportTemplateVO contains an array of ReportTemplateParameterVO objects,asillustratedinfigure5.5.

Figure5.5:CompositePatternwithValueObjectContext

BUSINESSLOGICLAYERObjectsinthebusinesslogiclayercombinedatawithbusinessrules,constraints,andactivities.BusinessobjectsshouldbeseparatedfromDAOs,entityobjects,VOs,andtheservicelayer,suchaswebservices,tomaximizethepossibilityofreuse.Businessobjectsoftenuseandcoordinate theactivitiesofmultipledataaccessobjects.

Business objects should be deployment independent and self-contained.Business objects should be easily usable in batch jobs as well as webapplications or thick-client applications. Business logic objects utilize dataaccess classes and reference entity and value objects, but don’t referenceanything in the presentation layer.Wewill find out that the presentation layerusesthebusinesslogiclayer,nottheotherwayaround.

Business logiccontains transactionscripts foranyworkperformedby theapplication. For example, if credit checks are automatically initiated for new

customers,thebusinesslogicclassmanagingsavingnewcustomers’informationmight also initiate the credit check for that customer. This action might beinitiated by a business user via a web application or initiated by a batch jobprocessing a purchased customer base. The business logic class makes noassumptionsastothecontextofitsexecution.

CommonPatternsOne of the most frequently used patterns in the business logic layer is theTransaction Script pattern. This pattern basically looks at an application as aseries of discrete transactions. For example, in banking, common transactionsaredefininganewcustomerandopeningnewbankaccountsforthatcustomer.Youcanimaginetransactionstofindanaccountbalanceaspartofvalidatingafinancialtransaction,asillustratedinfigure5.6.Amoredetaileddefinitioncanbefoundhere:http://martinfowler.com/eaaCatalog/transactionScript.html.

TheTransactionScriptpatternisoftencriticizedasnotbeingobjectoriented.That is true. It is so popular because it adheres to the practice of keepingsoftwareassimpleasitcanpossiblybe.

Figure5.6:TransactionScriptExample

Layered initialization is a pattern you will commonly use when you havedifferent varieties of the same object. For example, most applications havedifferenttypesofusers.Asshowninfigure5.7,youmighthavetrustcustomerusers,corporatecustomerusers,bankingsupportusers,applicationadministratorusers,andsoon.All theseusers sharecommonalitybutalsohaveaspects thatareunique.

Figure5.7:LayeredInitializationPatternExample

When the samebusiness objectmight have to produce different outputs orusedifferent inputs,youwillmost likelyuse theadapterpattern.Consider theexample shown in figure 5.8, a reporting business object that has severaldifferent delivery mechanisms—e-mail, ftp—but all other processing is thesame. Furthermore, there are existing utilities to perform the e-mail and ftpdeliveries, but they don’t implement the interface currently needed for theapplication.Theadapterhastheresponsibilityofimplementingtheinterfaceandutilizing any third-party product needed to actually accomplish the reportdelivery.

Figure5.8:AdapterPatternExample

Liketheadapterpattern,thestrategypatternisusedwhentheactivitiesofabusinessobjectarelikelytovaryaccordingtothecontext.However,theadapterpattern leaves the activities of a class constant while dynamically varying itsinputs and outputs, and the strategy pattern makes the activities of a classdynamicwhileusingconstantinputsandoutputs.It’slargelyadifferenceintheperceptionof“who’stheclient.”Figure5.9illustratesthestrategypattern.

Figure5.9:StrategyPatternExample

DEPLOYMENTLAYERDeploymentwrapperspublishbusinessobject functionality toJavaclasses thatcould be on separate machines (including anything in the presentation tier).Examplesofdeploymentwrappersincludeenterprisebeans(e.g.,sessionbeans,message-drivenbeans)andwebservices.

Promotingreuseisthemotivationfordeployingbusinessfunctionalitysothatit can be called by other applications. That is, it’s better to reuse existingfunctionality than to reinvent it. Sometimes the functionality to be reused ischangingfrequentlyorhasonerousresourcerequirementsthatmakeitdifficulttomerelyincludethatfunctionalityinyourapplicationascommoncode.

Deploymentlayerclassespublishbusinesslogic.Service layerclassesutilizebusinesslogicclassesandreferenceentityclassesandvalueobjects.Theydonotreferencedataaccessclassesdirectly.

Donot implement business logic directlywithin deployment layer classes.Somedevelopersconsiderenterprisebeanstorepresentbusinesslogic.Althoughit is technically possible to consolidate what I call business objects andenterprisebeansintothesameclass,Idon’trecommendit.Keepingthebusinesslogic separate gives you complete deployment flexibility. You can deploy thesame business object as an enterprise bean, a message-driven bean, a web

service,orevenaclientapplicationwithnochangestotheunderlyingbusinessobject.Separating thebusiness logic intodeployment-independentclassesdoescreateadditionalclasses,buttheclassesarelesscomplex.

Trendtowardpublishingthatisanindependentunitofwork.Ifaremotecallsucceeds,anychangesmadebythatremotecallwillbecommittedandwillnotparticipateinarollback.Ifyouneedtheabilitytorollbacktheworkperformedbya remotecall, itwouldbebetter to include thebusiness logiccode inyourapplicationwhereyoucancontrolthetransactionstrategy.

Trend away from publishing remote functionality with expected hightransactionvolume.Remotecallshavenetworkoverheadthatlocalcallsdon’t.Thisistrueregardlessofthedeploymentwrapperchosen.

ChoosingDeploymentWrappersYoucanhavemultipledeploymentwrappers for the samebusinessobject.Forexample,itisnotuncommontocreateamessage-drivenbeanandawebservicedeploymentforacustomerobject.

Each type of deployment wrapper has its advantages and disadvantages.Choosingwhich type of deploymentwrapper to use is difficult if you haven’tsubstantiallycompleteduse-caseanalysisandprototyping(chapter3)ordefiningapplicationinterfaces(chapter4).Table5.3summarizesthedifferencesbetweenthetypesofdeploymentwrappers.

Table5.3:FeaturesofDeploymentWrapperTypes

Feature EJBWeb

Services RMI HTTP

Callerplatformrequirements Java-compliantonly

Any Any Java- Any

Communicationmethodsupported Synch.only Both Both Synch.only

Synch.only

Coupling Tight Loose Loose Tight Loose

Supportsclusteringforscalabilityandavailability?

Yes Yes Yes No Yes

Facedwithdecidingwhichdeploymentwrapperstouseandwhichbusinessobjectstopublish,askyourselfthefollowingquestions;youranswerswillhelpyounavigatethroughthedecision-makingprocess.

Isyourbusinessobjectcalledfromapplicationsthataren’tJava?This functionality is commonly published as a web service.Web services

completely eliminate any language-to-language restrictions by encoding allcommunication in XML using a SOAP format. Because web services don’trepresent a programmatic coupling, they need very little deploymentcoordination.Webservicesarewidelyusedandoftenthepreferreddeploymentwrappingtechnology.

If yourmessaging vendor supports JMS and also has a nativeAPI for theforeignapplicationplatform,youshouldbeabletodeploythisfunctionalityasamessage-drivenenterprisebean.

DoesyourbusinessobjectreceiveandprocessmessagesviaJMS?Functionality supporting JMSmessage receipt andprocessing is commonly

implementedviaamessage-drivenenterprisebean.Thatbeanutilizesbusinesslogic classes to perform whatever work is required to process the message.Although the JMS standard was created and refined in the last few years,messaging technology has existed for more than a decade. Most messagingtechnologyvendorshaveimplementedtheJMSinterface.Messagingisgoodfortransmittinginformation.Thistechnologyisdesignedmoretoguaranteedeliverythantoissueasub-secondresponsetime.

Doesyourbusinessobjectrequiretwo-phasecommitfunctionality?If itdoes,deploy thebusinessobjectasa sessionbean.Two-phasecommit

functionalityrequiresJTAandisprovidedbyJavaEEcontainers.WebservicesorservletsrunningfromwithinaJavaEEcontainerwillhaveaccesstoJTA,butthesedeploymentsmaybeusedinenvironmentsthatdon’tsupportJTA.

CommonPatternsThe pattern commonly used for deploymentwrappers is a combination of thesession façade pattern and the proxy pattern. This combination (or slightvariationsthereof)worksforallthedeploymentwrappersthatIcanthinkof.Thesession façade pattern has been especially popularwithEJB deployments, buttheconceptisvalidformosttypesofdistributedobjects.

Twocommondesigngoalsfordeploymentwrapperssuchasenterprisebeansor web services are to minimize network traffic and to minimize changes.Façadesminimizenetworktrafficbyallowingthepublishedfunctionalitytobecoarse-grained. That is, using façades, remote calls to the remote service caninitiate processing of business logic over a larger amount of data or combine

lowerlevelbusinesslogicfeaturesinasinglecall.Itisoftenmoreimportanttominimize the number of calls to remote services, even if some of the data inthosecallsorreturnsfromthosecallsarelargerasaresult.

Façades allow you to minimize changes in features published to remotecallers.Thatis,itpreservestheabilitytorefactorandchangethebusinesslogiclayer or other layers of the application and keep the façade publishing thatfunctionalitytoremoteapplicationsunchanged.Thisiscustomerfriendlyinthesensethattheservice’sremoteapplicationsarecallingchangelessfrequently.Italsopreservesyourabilitytorefactorandchangetheapplicationpublishingtheservicewithoutaccidentallyimpactingcustomers.

Somedevelopers like topublish thebusiness logic layerobjectsdirectlyaswebservicesorenterprisebeans.Thisisusuallyanattemptatsimplificationandreducing complexity.But the troublewith that approach is that changes to thebusiness logic layer thenpotentially changehow those services are called andused.Thismeansthataninnocentrefactoringin thebusiness logic layermighthave unintended consequences for applications calling those services. Figure5.10graphicallyillustrateshowyoucaneffectivelycombinethesessionfaçadeandproxypatterns.

Figure5.10:SessionFaçadePatternwithProxyPattern

FURTHERREADINGGamma,Erich,RichardHelm,RalphJohnson,andJohnVlissides.1995.DesignPatterns.Reading,MA:Addison-Wesley.

CHAPTER6

CREATINGOBJECTMODELS

Application architects are responsible for leading the application designprocess. In this role, the architect is as much a facilitator as an applicationdesigner.Thischaptershowsyouwaystoutilizeuse-caseanalysisalongwiththelayeredapproachdescribedinthepreviouschaptertoconstructeffectivedesignsforJavaEEapplicationsanddocumenttheminanobjectmodel.Alongtheway,I’llsharesometechniquesforleadingagroupdesignprocess.

Finished use cases are essential for effective application design. Withoutthem,theobject-modelingsessionswillproducemorequestionsthananswers.Ifyoudofindvaguepointsorunaddressed issues in theuse-casedocumentation,apply the technique of making assumptions to fill the gaps. Document theassumptions youmake so you can confirm themwith the business side later.Youruse-caseanalysisismorelikelytobeincompletewhenyou’reworkingonalargeproject.

Object-modelingexercisesareapplicablefortheJavaportionsofaJavaEEapplication that are customwritten (e.g., not provided by a software vendor).Modelingofthird-partysoftwarecomponentsshouldbelimitedtothoseclassesdirectlycalledbyyourapplication.

It is not necessary to model 100 percent of the application. This isparticularlytruewhenlayeredarchitecturesareutilized.Objectmodelswillmostlikelybeneededforthevalueobjectandbusinesslogiclayers.Forinstance,theobjectmodelof the entire entity layerwill beobviousonceyou’ve completedthe datamodeling portion of the design (covered in the next chapter) as eachclasswill have a one-to-one relationshipwith a table. Furthermore,many JPAimplementationswillgenerateclassesmappedtoadatabase.Similarly,thedataaccess layer classes usually have a one-to-one relationshipwith entity classes(e.g., a customer entity class will likely have a customer data access class tohandleI/O).Concentratemodelingactivitiesonthemostcomplexportionsoftheapplication(typicallyinthebusinesslogiclayer).

The application architect is responsible for facilitating design discussions,whichshouldinvolvethebusinesslogicandpresentation-tierdevelopersinthe design process. Because of its subjective nature, the object-modelingprocesscanbea largesourceof frustrationandaprojectbottleneck. I’veseensomeprojectswherethearchitectproducestheobjectmodelprivatelyandthenattemptstocoerceotherdeveloperstofollow.Althoughalonemodelermaybeable toproduceanobjectmodelmorequickly thana team, themodel ismorelikelytocontainerrorsandomissions,andonlythearchitectunderstandsitandisloyaltoit.

When themodel is producedprivately, it doesn’t get substantivedevelopersupport. After all, if developers can’t understand or agree with a plan, theycertainlywon’twant to follow it.Manydevelopers react toarchitect-producedmodels by ceasing to contribute anythingmeaningful to the project from thatpoint.Thearchitectmaywant to“draft”amodelasaway tomove thedesignprocess along, but developers should clearly understand that this draft ispresentedsolelytopromptdiscussionandisentirelysubjecttochange.

Asapracticalmatter,whenIneedtogetmeaningfulsupport frommultipledevelopers, I go through the longer exercise of forming the plan collectively.Developerswhohavehadinputtoamodelandrepeatedopportunitiestosuggestenhancementstoitaregoingtobemoreenthusiasticaboutimplementingit.

Appoint a scribe for all modeling sessions. It’s difficult to facilitate designsessionsandtakeaccurateandcompletenotesoftheitemsdiscussedatthesametime.Asthearchitectisusuallyleadingthesession,oneofthedevelopersshouldactasscribe,perhapsonarotatingbasis.Afterthedesignsession,thescribeisresponsible for updating the object model to reflect changes discussed in thesession.

The remainder of this chapter presents a framework you can use to guidedevelopment staff through the object-modeling process. The first step in theprocessistoidentifythemajorobjectsinyourapplicationusingtheusecasesasaguide.Next,yourefinetheseobjectsintoclasses,determinehowtheyinteract,andidentifyattributesandmethods.Throughoutthechapter,Ishowyouhowtostreamlinetheprocessandavoidthoseannoyingbottlenecks.

IDENTIFYINGOBJECTSIdentifythemostimportantconstructs.Nounsinusecasesaregenerallygoodcandidatesforclasses.Thusagoodwaytostartidentifyingobjectsisbyreading

theusecasesandextractingalistofallthenouns.(Youcanignoresysteminthebeginning phrase “The system will” because it’s merely part of the use-caseformat.)

Atthispoint,youshouldinterpretmyuseofthewordobject loosely.Intheearlystagesofdevelopment,it’simpossibletoknowenoughabouttheseobjectstounderstandexactlywhichclassesyouwillderivefromthem.Notethatmyuseofthetermobjectdiffersfromsometextsthatusethetermtorefertoaninstanceofaclass.

Don’tbotherwithattributionorrelationshipsat this stage.Attribution andrelationshipsareimportant,butidentifyingthemtooearlywillbogyoudownintoomuchdetailandwillthrowtheteamintofrequenttangents.Fornow,trynottobeconcernedaboutprocess;focusinsteadondataorganization.

Asobjectsareidentified,recordpersistencerequirements.Someclasseswillrepresentdata thatyourapplicationhas tostore,usually inadatabase,andaresaidtobepersistent.Infact,persistentobjectsfrequentlyappearasentitiesinthedata model. I often record objects with persistent data as entities in the datamodelwhen they’re identified in theobjectmodel. I discuss datamodeling indetailinchapter7.

Objects identified at this stage are high level. You will further refine andexpandthemlaterintheprocess,usingobjectstodeterminespecificclasses.

OBJECTIDENTIFICATIONEXAMPLELet’s use an example paraphrased from a reporting system I recentlyimplemented.Theteamdefinedthefollowingusecases:

ThesystemwillprovideaninterfacethatwillacceptreporttemplatedefinitionsfromanexistingMVS/CICSapplication.AreporttemplateconsistsofanID,aname,alistofparametersrequiredtorunthetemplate,andalistofdataitemsproducedbythetemplate.Thesystemwillallowapplicationadministratorstocontrolthereporttemplatesthatusersbelongingtoatrustcustomerorganizationcanrun.Thesystemwillrunreportsatleastasfastasitspredecessorsystemdidonaverage.Thesystemwillrestrictreporteddataforalltrustcustomeruserstothatof

thetrustcustomerorganizationtowhichtheybelong.Thesystemwillallowbankingsupportuserstoexecuteallreporttemplatesusingdatafromanytrustcustomerorganization.

Lookingatthenounsintheusecasesinorder(ignoringsystem,asmentionedearlier)gaveusthelistthatappearsinthefirstcolumnoftable6.1.

Table6.1:ObjectIdentificationExample

Noun(fromusecase) Object

Interface ReportTemplateInterface

Reporttemplate ReportTemplate

Listofparameters ReportTemplateParameter

Dataitem ReportDataItem

Applicationadministrator ApplicationAdministrator

Trustcustomerorganization TrustCustomerOrganization

Trustcustomeruser TrustCustomerMember

Reporteddata Report

Bankingsupportuser BankingSupportUser

Nextwerephrased thenouns tomake themself-containedobjectnames,asshown in table 6.1. By self-contained, I mean that object names shouldn’tdependoncontexttoprovidemeaning.Forinstance,interfacefromthefirstusecase became ReportTemplateInterface and list of parameters becameReportTemplateParameter. The fact that our use case referred to a “list” ofparameterswasdocumented as a relationship.Themoredescriptive theobjectname,thebetter.AlltheobjectswerepersistentexceptReportTemplateInterface.(Note that theword interface in thisusecase refers toanapplication interfaceandmaynotimplyuseofaJavainterfaceconstruct.)

Three types of users appear in the list: application administrator, trustcustomer member, and banking support user.When we got to attribution, werecognized that there was another object, User, with different subtypes.Inheritancerelationshipslikethisareeasiertorecognizewhenitcomestimeforattribution,solet’sleavetheobjectlistasitisfornow.

An alternative to merely identifying nouns is to do the data-modelingexercise first. All identified entities are good object candidates. Many of the

objectsweidentifiedinthisexamplewouldmakegoodentitycandidatesaswell.Seechapter7fordetails.

Some of these objects were implemented as classes in multiple softwarelayersintheapplication.Thisprocessisthefocusofthenextsection.Definingandillustratingtheselayerswasdescribedinchapter5.

TURNINGOBJECTSINTOCLASSESOnce you have identifiedmajor objects in the application, you need to refinethoseobjectsintoclassesandorganizetheminaframework.

Afteridentifyingobjects,youneedtoidentifywhichlayerstheypertainto.Itiscommonforobjectstohavemultipleroles.Anyobjectyouhaveidentifiedas playingmultiple roles (e.g.,manage data access, implement business rules,etc.) must get counterparts in multiple layers. For example, ReportTemplate,ReportTemplateParameter, andReportDataItem from table 6.1 had persistencerequirements as well as requirements as business objects. Therefore, theyappearedasclassesinatleastthedataaccesslayer,thebusinessobjectlayer,andtheentitylayer.

Defineseparateclassesforeachobjectineachlayer. Ifyoudefinethesameclassforeachoftheseroles,theclassesgettoolargetoeffectivelymaintainandyouloseallthebenefitsfromsoftwarelayering.

From the object identification example, consider object ReportTemplate.ClassReportTemplateDAO,residinginthedataaccesslayer,wasresponsibleforreading and writing template information using a relational database.ReportTemplateEntityintheentitylayerdescribedallcharacteristicsofareporttemplate(e.g.,itsname,datatype,displaylength,etc.).ReportTemplateManagerinthebusinesslogiclayercoordinatedandenforcedallrulesforcreatinganewreport template. And ReportTemplateManager coordinated report templateinformation, template parameter information, and any other informationnecessaryforrunningoreditingareport.

DETERMININGRELATIONSHIPSA relationship describes how different classes interact. You can determinerelationships after you’ve identified individual classes. The UML literaturedocuments several categories of object relationships. Most applications onlyneedthefourtypesdescribedinthefollowingparagraphs.

Dependency(uses)relationshipdocumentsthatoneclassusesanotherclass.At a code level,using another classmeans referencing the class in someway(e.g., declaring, instantiating, etc.). Because this relationship type is strikinglysimilar to the association relationship type, I usually ignore the differencebetweenthetwotypesasunnecessarycomplexity.Therelationshipinfigure6.1isreadas“CustomerusesAccount.”

Figure6.1:DependencyRelationshipIllustration

Generalizes (extends) relationship documents that one class extends, orinheritsthecharacteristicsof,anotherclass.Mostmediumtolargeapplicationshaveahandfulofthistypeofrelationship.

Anextendsrelationshipisdenotedbyasolidlinewithahollowarrow.Therelationship emanating from TrustCustomer in figure 6.2 is read as“TrustCustomerextendsCustomer.”TheattributesofCustomerwillbeavailableandusableinallchildren.

Figure6.2:ExtendsRelationshipIllustration

Realization(implements)relationshipdocuments thataclass implementsaninterface.Animplementsrelationshipisdenotedbyadottedlinewithahollow

arrow.Therelationshipinfigure6.3isreadas“E-mailDeliveryTypeimplementsReportDeliveryType.”

Figure6.3:ImplementsRelationshipIllustration

Aggregation (collects) relationshipdocuments that a class collectsmultipleoccurrencesofaclass.Acollectsrelationship isdenotedbyasolid linewithadiamond next to the class doing the collecting. The relationship in figure 6.4reads“CustomercollectsAccount.”

Figure6.4:CollectsRelationshipIllustration

Don’tdocumentformalrelationshipstovalueobjectsorentityobjects.VOsandentitieshavesomanyrelationships that if theyaredocumented, themodelbecomes unreadable and unusable.After all, the purpose of creating the classdiagram is to make the application easier for the team to understand andimplement. Inanycase,VOrelationshipsareeasyfordevelopers to figureoutfromthemethodsignatures.

IDENTIFYINGATTRIBUTESAttributesarefieldsthataclasscontains.Atacodelevel,attributesareinstance-levelvariabledeclarations.MostattributionoccurswithVOs,withotherobjecttypesreceivinglittleattribution.

Ideally,attributesshouldbebase,notderived.Abaseattribute is atomic—thatis,itsvalueisnotderivedfromthevalueofotherelementsortheresultofacalculation. Conversely, a derived attribute is made up of the values of otherelements. For example, consider a CustomerVO class that has firstName,lastName,andfullNameattributes.TheattributefullNameisderivedbecauseitismadeupofthefirstandlastnames.

Avoid declaring derived attributes. Derived attributes, like fullNamementioned in the previous paragraph, only give you more to maintain. If a

customer changes his or her last name, the values of two attributes need tochange. InsteadofmakingfullNameanattribute, itwouldbebetter tocreateaconveniencemethod,suchasgetFullName(),thatdoestheconcatenation.

IDENTIFYINGMETHODSMethods arewhere the action is.Methods are invoked primarilywhen a userdoes something, when something that was scheduled occurs, and whensomething is received from an external interface. A common way to identifymethods is toanalyzeeacheventanddocument themethodsneededalong theway.During the course of identifying themethods you’ll need, you’ll usuallyidentifynewclasses.

Startingwithuseractions,Iusescreensfromtheprototypetodrivemethodidentification.Consider an application login as an example.Most applicationscustomize themain screen based on a user’s identity and preferences. For themoment, assume that authorization and authentication is provided by theenterprisearchitectureandnotatanapplication level.Furtherassume thatyouneedtoinvokesomethingthatwillgetuserspecificsfromthesecuritypackage,invoke something to retrieve that user’s options settings, anddisplay themainapplicationpage.

If you use Struts, you’ll need some kind of action class that can get userspecifics from the security package, using the package to look up customerpreferences(whichwillbeused togenerate themainpage). Ifyouhaven’tyetidentified an action class to do this, add it to themodel. Ignoring the securitypackageitself,sinceit’soutofscope,youthenneedamethodsomewhere thatallowstheuserpreferencelookup.

Rememberfromourdiscussionofsoftwarelayeringinchapter5thatclassesinthepresentationtierusebusinesslogiclayerclassesratherthanusingDAOsdirectly. Most applications identify a user object (or something similar) thatmanifests intoaDAOclass,anentityclass,andabusinessobject. ItwouldbelogicaltoaddafindById(StringuserId)methodtoouruserbusinesslogiclayerclass. It would also be logical for that method to return a UserEntity, whichincludesinformationaboutpreferences,asaresultofthecall.

Pass and returnVOs or entities instead of individual data items.Doing sodecreasesthenumberofargumentspassedbetweenmethodcallsandmakesformorereadablecode.

Thephysical lookupof theuserpreferences isusuallydelegated to at least

oneDAO.ItwouldbelogicaltohaveaUserDAOthathasafindById()methodonitthatwoulddothelookup.

Bynow,you’reprobablywonderingwhyyoudon’tjusthavetheActionclassinvoketheDAOdirectly.Itwouldappeartobesimplerbecauseitwouldcutoutseverallayersofclassesthat,inthisexample,appeartobeaddingverylittletothefunctionalityoftheproduct.Technically,youcouldhavehadtheActionclassinvoke the DAO directly, but doing so would have greatly added to thecomplexity of the Action class, which isn’t easy to debug, and would haveeliminated the insulatingbenefits of software layering, as discussed in the lastchapter.

Figure6.5illustratesanobjectmodelfortheexamplejustdiscussed.

Figure6.5:ObjectModelExample

SHORTCUTSOvertheyears,I’veadoptedseveralshortcuts thatdecreasethetimeandeffortrequiredintheobject-modelingphase.

Assume that all documented attributes will have accessors (get methods)andmutators(setmethods).Thissimplifiesthemodelandeliminatesalotofboringbusywork. Italsomakes themodeleasier toreadand thusmoreuseful.Forexample,ifyoudocumentthataCustomerVOclasshasalastNameattribute,you should be able to assume the existence of getFirstName() andsetFirstName()methodswithoutexplicitlydocumentingtheminthemodel.

Omitrelationships toobjects in theJDK. Including these relationships addsvery little value but a lot of complexity, making themodel hard to read. Forexample, many attributes in the JDK are strings. Technically, any classcontaining a string attribute should have a relationship to the java.lang.Stringclass. In a typical application, documenting these typesof relationshipswouldadd hundreds or thousands of relationships to your model and provide nobenefit.

ForgetaboutgeneratingcodefromUML.Myexperienceisthatit’susuallyanet timeloss.Theminutelevelofdetailyouhavetotypeinthemodelusuallyexceeds the time it would take to code it using any integrated developmentenvironment(IDE).Ontheotherhand,generatingUMLfromexistingcodecanbeextremelyvaluableandeasytodoifyourIDEsupportsit.

Don’t attempt to micromanage the coding when determining methods.Leavesomeworktothedeveloper.Ifthedevelopmentteamstartsdocumentingprivatemethods,it’sgoingtoofar.

EXAMPLE:ADMIN4JAdmin4J(www.admin4j.net)isanopensourceproductthatprovidesbasicJavaEEapplicationadministrationandsupportfeaturesforsupportdevelopers.Oneofitsfeaturesistotrackandsummarizeexceptionsgeneratedbyapplicationssothat ongoing application issues can be easily identified and prioritized. In theinterestoffulldisclosure,I’macommitterfortheAdmin4Jproject.

AdetaileddescriptionofthisfeaturetakenfromtheAdmin4Jprojectwebsiteis as follows: Admin4J tracks all logged exceptions and combines andsummarizesall“like”exceptions.Currently,exceptionsloggedwithLog4Jand

JDK Logging are tracked. Additional loggers will be added as user demanddictates.

DisplayFeaturesExceptionsaresortedfromthemostfrequentoccurringtotheleast.Exceptionsarepersistedandsurviveacontainerrecycle.Administratorscandeleteexceptionsthattheydeemdatedandnolongeroccurring.

Thelengthoftimecoveredbyexceptionstatisticsisconfigurable(defaultstothirtydays).

In addition to these explicit requirements, there are a couple of implicitrequirements to keep in mind. This feature needs to be easily installable. Aninstallprocessthatisdifficulttounderstandorhasalargenumberofstepsisnotlikely to be used; most developers are very busy people. Secondly, theperformanceimpactofthisfeatureneedstobeminimal.Ideallyapplicationswillthrow exceptions rarely, but that isn’t always the case. Should this featureaccidentally cause a material performance impact to end users, it would bepromptlyuninstalled.

Althoughthisfeaturesetisnotreallywrittenasusecases,itconveysmuchofthe information thatwouldbe in those use cases and canbe used in a similarway. In examining this feature set within the context of a software layeringframework as discussed in the last chapter, we can start associating thesefeatureswithappropriatesoftwarelayers.

I often start by identifying entity classes that are passed among the dataaccess, business logic, and presentation layers of an application. As entityclassesarestoredandaretypicallynouns,theentitymosteasilyidentifiedwiththisfeaturesetisException.Astheentityname“Exception”isalreadytakenbythe JDK,and the information thatneeds tobe stored is really informationandstatistics regarding that exception, the entitywas named ExceptionInfo. Ifwelook at the screen shot in figure 6.6, specific information retained about anexceptionisthefollowing:

ClassnameMessagefromlastoccurrenceThetotalnumberofexceptionstracked

FirstandlastoccurrencedatesAssociatedstacktrace

Itforeshadowsthenextchapter,butperformingadatamodelingexerciseisappropriate at this point. As explained in the next chapter, a data model willmakeidentifyingtheentityclassesveryeasy.

Thestacktraceassociatedwiththeexceptionneedsadditionalthoughtinthatitisn’tabaseattribute.It’sactuallyacollectionofexecutionpointsexpressedasaclass,methodname,andlinenumbercombination.Theorderoftheexecutionpointswithinthecollectionindicatesthecallhierarchy.Asitturnsout,theJDKalready has a representation for these execution points in a class calledjava.lang.StackTraceElement.

Anobjectmodelfortheentitylayerportioncanbefoundinfigure6.6.Notethat I’ve assumed the existence of accessors and mutators and not directlymodeled them. Also, I normally don’t directly model classes in the JDK andrelationshipstothem,butthisparticularrelationshipisimportantandisneededby developers to understand the design. Furthermore, StackTraceElement isreally a value object and is not nearly as innocuous as the use ofmost otherclassesinthejava.langpackage.

Figure6.6:Admin4JExceptionFeatureEntityLayerDiagram

Havingidentifiedtherelevantentityclasses,wecanstartmodelingthedataaccesslayer.Thefeaturerequirementsforpersistencedon’tspecificallyspecifyastoragemechanism.Infact,theonlyrequirementisthattheproductremembersexceptionstatisticsbetweencontainerrecycles.Whilewemightwanttoprovideadditionalreportingfeaturesdowntheroad,displayrequirementsdon’tsuggestanytypeofflexiblesearchrequirementsregardingexceptionstatistics.Itappearsthatallwereallyneedtodoisamassreadandwriteofexceptionstatistics.

Dependingonhowlargetheexceptionstatisticsinformationturnsouttobe,

reading andwriting enmasse on a frequent basismight bematerial for someusers.Given this,adecisionwasmadetoseparatereadingandwritingactivityfromtheactivitytrappingloggingofexceptions.Thatis,wemadethedecisiontoconductthereadingandwritingactivityinathreadseparatefromthethreadsrunninguserwork.Wedidn’twanttoslowdownuseractivitywiththestorageofexceptionstatisticsthatwouldbeusedforlateranalysis.

In addition, we wanted to keep resource consumption by Admin4J to aminimum. Rewriting exception statistics after every update would ensure thatup-to-datestatisticsarecurrent,buttheresourceconsumptionwouldhavebeenlargeinsituationswherelargenumbersofexceptionswerebeingthrown.Asacompromise, a decision was made to persist exception statistics on aconfigurable interval. That would allow users to effectively balance resourceconsumptionwiththeneedtopersistcurrentstatistics.Asaconsequenceofthisdecision, thedataaccess layeronlyneedstoreadandwriteexceptionstatisticsenmasse;therewasnoneedforsinglereadandwriteoperations.

With a software package such as this, minimizing the dependency list isalwaysaconsideration.Withthatinmind,wedecidedtouseXMLasastoragemechanism for the first release and keep our options open for other storagemechanismsinthefuture.Whilethischoicedoesn’tofferthesameflexibilityasa relational database of some sort, it reduces dependencies for third-partydatabase software. It also reduces the install effort required. Given that thedecision has been made to support multiple storage mechanisms, a full dataaccessobjectpatternisappropriate.

Generally, a data access class is a factory for entity classes, and generally,therewillbeaone-to-onecorrespondencebetweenentityclassesanddataaccessobjectinterfaces.Anobjectmodelforthedataaccesslayerforthisfeaturecanbefoundinfigure6.7.

Figure6.7:Admin4JExceptionFeatureDataAccessLayerClassDiagram

At this point from the model of the entity classes, we have a plan fororganizing exception statistics and a list of what specific statistical attributeswe’re tracking. From the model of the data access layer, we understand howinput/output for this section of the application is going towork.We have notmodeled the section of Admin4J that actually examines exceptions that arelogged,analyzes them to seewhichexceptionsare identical to those thathavebeen logged previously, and updates the relevant statistics. We’ve also madementionofthedecisiontostoreexceptionstatisticsataconfigurableintervaltokeepresourceutilizationlow.Thisactivityoccursinthebusinesslogiclayer.Foraproductsuchas this, thenatureof the logic layer ismore technical innaturethanyou find inmost JavaEE applications.A class diagram for theAdmin4Jbusinesslogiclayercanbefoundinfigure6.8.

Let’sstartby identifyingapreliminary listofclasses thatwillbeneeded inthe logic layer. Something needs to be responsible for analyzing generatedexceptions,determiningwhetherornotanexceptionlikeithasbeenpreviouslyobserved,andupdatingthestatisticsassociatedwiththatexception.Forthelackofabetterterm,let’scalltheclassthatdoesthisanExceptionTracker.

Fromtheplannedfeatureset,ExceptionTrackerneedsmethodstoinitiatethe“tracking” of an exception and retrieving exception statistics. Furthermore, tosupport the feature that “Administrators can delete exceptions that they deemdatedandnolongeroccurring,”amethodtodeletethereferencetoanexistingexceptionisalsoneeded.Asexceptionstatisticsarepersisted,itfollowsthattheExceptionTrackerwillrelyonthedataaccesslayer.

At this level, we also needed to formulate a plan for observing loggedexceptions.Howthis isaccomplishedisdictatedmoreby the loggingproductsthan anything else. Regarding Log4J, the easiest way to observe loggedexceptions is to implement a Log4J Appender. This is accomplished byextending a Log4J class called the AppenderSkeleton. Class

Log4JExceptionAppender fromfigure6.8accomplishes this. It stands to reasonthat this classwill rely on the ExceptionTracker to analyze the exception andupdateexceptionstatistics.

Regardingtheloggingframeworkthat’sincorporatedintheJDK,exceptionscan be observed by extending a Handler class (java.util.logging). ClassJdkLoggingExceptionHandler from figure 6.8 accomplishes this. It stands toreasonthatthisclasswillrelyontheExceptionTrackertoanalyzetheexceptionandupdateexceptionstatistics.

We also need a plan to supportwork thatwill happen in a separate thread(e.g., the periodic storing of exception statistics at a configurable interval andpurging aged exception statistics); we need a daemon thread for that type ofwork. In the class diagram, we’ve named this classExceptionTrackerCleanupTask.Thisclassleveragesagenericdaemonclassusedby other portions ofAdmin4J. That information is really out of scope for theportionwe’remodelinghereandhasn’tbeenincluded.What’simportantisthatwe’ve identified a class toperform thisworkand the fact that it operates in adaemonthread.

The decision to persist statistics on a configurable time interval makes itpossible to lose trackof exceptionsgeneratedbetween the time statisticswerelast persisted and shutdown of the JVM (e.g., application is shut down formaintenance or software updates). To minimize information loss, we’veimplementedashutdownhookthatwillbeexecutedwithagracefulshutdown.Thishookwillpersist statisticsand terminate.Wewill still lose information iftheJVMprocessiskilledorsufferssomeothertypeofnongracefulshutdown.

Figure6.8:Admin4JExceptionFeatureBusinessLogicLayerClassDiagram

Atthispoint,allthatremainsfromamodelingperspectiveisthepresentationlayer. As Admin4J is a generic tool, we can’t assume the existence of anypresentationframework,suchasStruts,JavaServerFaces,Wicket,oranythingelse.Nordowewanttoimposealargeconfigurationeffortonusers.Atthesametime,writingandmaintaininguserdisplay logicentirelywithinservletcode istediousandtimeconsuming.

Tominimizeourdependencyandconfiguration footprint,yetprovide somebasic presentation capabilities, we adopted Freemarker(http://freemarker.sourceforge.net/)asadisplaymechanism.Weconfiguredouruse of it so that all templates we use are sourced from the Admin4J jar.Wedidn’t want users to have to copy templates or individual JSPs into theirapplicationwebroot.

This presentation method requires users to register a servlet in theapplicationsweb.xml file.As all ofAdmin4J’s display pages follow a similararchitecture, we became concerned that the servlet registration requirementwouldbecomeoppressive.Tosolve that issue,wecreatedahomepageservletthat contains links for all Admin4J pages, including the exception statisticsdisplaypagewe’rediscussinginthisexample.Usersneedonlyregisterthehomepageservletonce,andallotherpagesarehandledautomatically.Ofcourse,userscan still install pages separately if they don’t want to install all Admin4Jfeatures,butthat’stheuser’sdecision.

The ExceptionDisplayServlet handles display for the exception statistics

display page. The ExceptionDisplayServlet extends the AdminDisplayServlet,which provides basic plumbing code to generate output from Freemarkertemplates andwrites that generated content to a user’s browser.Both of theseservlets rely on functionality contained in the Admin4JServlet class, whichhandlesbasicconfigurationtasksforallAdmin4Jfunctionality.

AclassdiagramforthepresentationlayerforthisportionofAdmin4Jcanbefoundinfigure6.9.

Figure6.9:Admin4JExceptionFeaturePresentationLayerClassDiagram

After the reader has reviewed this example, I expect several follow-upquestions.

DoIneedtomodeleveryportionofallapplicationsinthismuchdetail?Inall probability, models such as these usually aren’t updated over time.Consequently, theyhave themostvalue for the initialdevelopmenteffort.Theamount of modeling performed should be just enough to support the initialdevelopmenteffort.

Furthermore, let’s distinguish between “modeling” and the act ofdocumenting that model in a modeling tool or graphics design package. Forthosewithmuchmodelingexperience,thelatterusuallytakesmoretimethantheformer. I mentally construct models for most of my projects regardless ofwhetherornotIwritethosemodelsdownasacommunicationmechanismwithother team members. It leads to cleaner code and more maintainableapplications.Furthermore,ithelpsmeworkinanorganizedfashion.

Theamountandqualityofmodeldocumentationneededdependsonproject

complexity, the size of the project, and how many developers on the projectdon’thaveexperienceworkingwithyouonpreviousprojects.Foraprojectwithone or two developers,much less documentation is needed than for a projectwithateamoftwentydevelopers.Infact,foraprojectwithonlyonedeveloper,aformallydocumentedobjectmodelmightnotbeneeded.

Also,ifyou’reworkingwithdevelopersunfamiliarwithyourmethods,theywillneedmoreguidancethanthosewho’veworkedwithyoubefore.WithoneteamI’veworkedwithforseveralprojects,Icanmodeltheentitylayerandthemost complicated portions of the business logic layer, and not formallydocumentotherportionsofthemodel.

The entity layer largely dictates the organization of the data access layer.Consequently,oncetheentitylayermodeldocumentationisproduced,youmightnothavetodocumentthedataaccesslayercompletely.Onceyoucommunicatethedataaccesspatterntobeused,itcanbeappliedtoanyentity.Forexample,the data access layer persisting performance statistics for Admin4J is verysimilarinconcepttowhatwaspresentedregardingexceptionstatistics.

If you encounter a portion of your development project that is difficult foryoutomodel,that’sanindicatorthatthemodelforthatportionoftheapplicationshouldbedocumentedanddiscussedwiththedevelopmentteam.Ifit’sdifficultfor you, itwill likelybedifficult for others, and all developers for theprojectshould be on the same page and understand the design being constructed.Furthermore, the perspectives and opinions of others might help you clarifyissuesandconcerns.

Whatmodelingtoolsdoyouuse?Iusewhatmyclientsuse.Forthosewithoutmodeling tools, I recommendArgoUML(http://argouml.tigris.org/). It’s averyactive open source project that I find moderately easy to use. In fact, objectmodelsforAdmin4JinthisexamplewereproducedusingArgoUML.

Howcanyouvalidate thatyourobjectmodelsarecorrect?Goodquestion.Wedon’thavecompilersorothertoolsthatwillvalidateobjectmodels.Onewaytotestispeerreviewbydevelopers.Holdareviewsessionwithothersfamiliarwiththerequirementsandprovidethemwithareviewandexplanationofyourmodels. Often, others will have insight and may point out defects or issuesbefore construction. Furthermore, defects in the model will become moreapparentduringconstruction.

Compare yourmodel to the code actually developed. Therewill always be

subtle adjustmentsmade to the design (e.g., attributes added,methods added).But if fundamental classes and relationships between software classes asconstructeddiffersubstantiallyfromyourmodel,itcouldindicatedefectsinthemodel.For this reason, Iusuallyparticipate in theconstructionphaseso that Icanlearnfrommymistakes.

FURTHERREADINGGamma,Erich,RichardHelm,RalphJohnson,andJohnVlissides.1995.DesignPatterns.Reading,MA:Addison-Wesley.

CHAPTER7

CREATINGTHEDATAMODEL

Most books about Java EE skip the data-modeling and relational databasedesignphasesofdevelopment.ButIhavefoundthatbothstepsarecriticaltothesuccess of a Java EE application. As part of the development team, anapplicationarchitectshouldhaveabasicknowledgeofdatamodeling.Further,in some companies, the architect is responsible for designing the applicationdatabase. Just as object-modeling exercises help produce good code, data-modeling exercises help produce good database designs. (I have to admit,however, that themanyyears I spent as adatabasedesigner andadministratormayhaveprejudicedmyviewsastotheimportanceofdatamodeling.)Evenifyourorganizationdelegates relationaldatabasedesignanddatamodeling tasksto a separate team, application architects should understand data modelingconcepts.Inanorganizationwithseparatedatamodelingteams,theapplicationarchitectusuallycommunicatesrequirementsandcoordinateswith that teamtoget the database designed and implemented. Understanding data modelingconceptswillallowthearchitecttostreamlinethisprocess.

Ialsorelyontheseconceptswhenmodelingtheentitylayer,asmostobjectmapping technologies rely on a one-to-one correspondence between entityclassesanddatabasetables.Forexample,abankingapplicationwithadatabasetable calledAccountmight bemapped to a Java class in the entity layer callAccountEntity. In fact, creating adatabasemodel for an application canmakemodelingoftheentitylayerintheapplicationmucheasier.Itisnotunusualfordatamodelingandobjectmodelingactivitiestooccurconcurrently.

Asthedatamodel(andresultingdatabasedesign)greatlyimpactsthedesignoftheentitylayerofyourapplication,apoordatabasedesignwillcreatecodingproblemsanddifficulties.I’veseenpoordatabasedesignsinflatetheamountandcomplexityofapplicationcodeproduced.Withthat increasedcomplexityoftencomesanincreasedfrequencyofbugreportsandalargerresourcerequirement

todiagnoseandfixthosebugs.Ensuringthatdevelopersareworkingwithahighqualitydatamodel(andresultingdatabasedesign)shouldbeahighpriorityforapplicationarchitects.

In addition, I find data-modeling concepts very useful in designing XMLdocument formats, such as DTDs and schemas. Applying data-modelingconceptstoXMLdocumentdesignisabitunconventional.Thethoughtprocessbehind deciding if a data item is an element or an attribute is very similar todeciding between entities and attributes in datamodeling. In addition, one-to-many relationships in data modeling translate directly to the child elementconcept in XML documents. I’ll provide some details and examples in thissectiontoshowhowyoucanimplementdatamodelsasXMLdocumentformats.

Although the popularity of NoSQL databases has grown in recent years, Idon’t see any signs that relational database technologies will be replaced anytime soon. NoSQL databases are targeted at extremely large data stores thatdon’thavethesametransactionguaranteesthatrelationaldatabasesdo.Inotherwords, NoSQL databases are used in cases where approximate answers areacceptable. Furthermore, asNoSQLproducts varywidely andhavedrasticallydifferent strengths and weaknesses, any advice on how to design NoSQLdatabases tends tobeproductspecific.ThebestattemptI’veseen todocumentgeneralizeddatamodelingtechniquesforNoSQLdatabaseshasbeenthisarticle:http://highlyscalable.wordpress.com/2012/03/01/nosql-data-modeling-techniques/. For now, because relational databases are part of most Java EEapplications, most application architects need to have at least a basicunderstandingofrelationaldata-modelingconcepts.Therestofthischapterwillfocusonrelationaldatabases.

If you’remore comfortablewith datamodeling thanwith objectmodeling,feelfreetotaketheeasierpathbydoingdata-modelingactivitiesbeforeobjectmodeling. All the entities (defined in the next section) in the data model arepotentialidentificationsofclassesintheentitylayer.Althoughthetwomodelingdisciplinesusedifferentterms,theyarequitesimilarconceptually.

KEYTERMSANDCONCEPTSAnentity issomethingyouwanttokeepinformationaboutandthusrepresentsinformationthatpersists(i.e.,iswrittentomedia).Usually,anentityisanoun.Althoughmostentitiesareimplementedasdatabasetables,thetermsentityandtable are not synonymous.An entity is purely a conceptual construct,with its

closestcounterpartinobjectmodelingbeingaclass.Goodexamplesofentitiesarecustomer,account,user,customerorder,andproduct.

In a relational database, an entity is implemented as a table. When youimplementyourdatamodelasanXMLDTDorschema,eachentitybecomesanelement.

Anentityoccurrence (sometimesshortened tooccurrence) isan instanceofanentity.Ifyou’remorecomfortablewithobjectmodeling,youcanthinkofanentityoccurrenceassimilartoinstantiatingaclass.Ifyoucan’tresisttheurgetoequateentitiesandtables,consideranentityoccurrenceasarowinatable.AndforXMLusers, an entity occurrence is like an individual element in anXMLdocument.

Anattributeisacharacteristicofanentity.Althoughattributescanbenouns,they usually don’t make sense outside the context of an entity. For example,attributesof aCUSTOMERentity couldbeCUSTOMER_ID,FIRST_NAME,LAST_NAME, STREET_ADDRESS, CITY, STATE, and ZIP_CODE.Attributes should be atomic—that is, they should be self-contained and notderivedfromthevaluesofotherattributes.

Aprimarykey is theoneattribute,orcombinationofattributes,ofanentitythat uniquely identifies an entity occurrence. For example, CUSTOMER_IDwould be a good primary key for the CUSTOMER entity, andACCOUNT_NUMBER and ORDER_NUMBER taken together would be agoodprimarykeyforanentitycalledCUSTOMER_ORDER.

Every entry must have a primary key. If, by chance, no combination ofattributesuniquelyidentifiesanentityoccurrence,makeupanattributetoserveasakey.Forexample,mostmanufacturersassignuniqueidentifiers(UPCcodes)to their products; but when they don’t, you might have to make up productidentifierstoserveastheprimarykey.

Arelationshipisanassociationbetweentwoentities.Outofthemanytypesof relationships that exist, three are commonly used: one-to-many, many-to-many,andsuper-type/sub-type.Inaone-to-manyrelationship,oneoccurrenceofanentityisassociatedwithpossiblymultipleoccurrencesofanotherentity.Forexample, a single customer could have multiple accounts or place multipleorders.Often, the entitywith a single occurrence is called theparent, and theentitywithmultipleoccurrencesiscalledthechild.Figure7.1illustratesaone-to-manyrelationship.

Figure7.1:One-to-ManyRelationshipERDiagram

NoticeinthefigurethattheACCOUNTentitycontainstheprimarykey(PK)columns of theACCOUNT_TYPE andCUSTOMER entities. Each additionalcolumninACCOUNTisaforeignkey(FK).Foreignkeysaretheprimarykeysof related entities that an entity uses for lookup purposes. The existence of aforeign key is an implicit result of creating a one-to-many relationship. Forexample, given an occurrence of ACCOUNT, related CUSTOMER andACCOUNT_TYPEinformationiseasytodetermine.

Somedata-modeling toolsprovide formany-to-many relationshipsbetweenentities. In a many-to-many relationship, each entity has a one-to-manyrelationship with the other. For example, customer orders can contain manyproducts, and each product can be purchased by multiple customers. It iscommon to rewrite amany-to-many relationship as two separate one-to-manyrelationships with a new entity defined as a cross-reference. Figure 7.2 is anexampleofamany-to-manyrelationship.

Figure7.2:Many-to-ManyRelationship

In a super-type/sub-type relationship, an entity refines the definition ofanother entitymuch the sameway as inheritance does in the Javaworld. Forexample,inbanking,acustomerentitymightbetoogenericforabankthathastrust customers, private banking customers, corporate customers, brokeragecustomers, and soon. In a Javaworld, thisverywellmightbemodeledas aninheritancerelationshipwherebankingcustomersarerepresentedbyaclassthatextendsCustomer(asinfigure7.3a).

Figure7.3a:InheritanceRelationship

Usingdatamodelingterminology,wewouldidentifyaCustomerentity thatis the super-type. We would also identify the Banking Customer, MortgageCustomer,andBrokerageCustomerassub-types.TheCustomerentitycontainsallattributescommontoallthreesub-types.EachoccurrenceofCustomerhasacorresponding occurrence in one and only one of the sub-type entities. Theterminologydiffers,buttheconceptisverysimilartoaninheritancerelationshipontheJavaside.

Super-type/sub-type relationships can be physically implemented in twoways.They can be expressed as separate entities or combined into one entity.Figure7.3billustratesarelationshipofthistype.Noticethattherelationshipsinthis example are all one-to-one and are all optional. Notice that attributescommon to all are assigned to theCustomer entitywhile the sub-type entitiescontainattributesspecifictotheirrespectivetype.

Figure7.3b:InheritanceExpressedasSeparateEntities

The second option for implementing super-type/sub-type relationships is tocombineallentitiesintoone.Withthismethod,theCustomerentitycontainsallattributesfromall fourentities,alongwitha“type”field(e.g.,Customer type)thatindicateswhattypeofentityrepresentsthatparticularrow.Forexample,iftheCustomer type isBanking, thatoccurrence isabankingcustomerandonlyattributes pertaining to banking customers (ONLINE_ACCESS_ALLOWED,CUSTOMER_ID, FIRST_NAME, and LAST_NAME) have values. Anillustrationofthistypeofimplementationcanbefoundinfigure7.3c.

Figure7.3c:InheritanceExpressedasCombinedEntity

Manydevelopersprefertocombinesuper-typesandsub-typesinthismanneras it reduces the number of entities and relationships. However, using thispattern, which attributes apply to which sub-types is not documented in themodelandmaycauseconfusionintheimplementation.

Itispossibletohaveentitiesrelatedtothemselves.Thisiscalledarecursiverelationship. For example, consider an EMPLOYEE entity withEMPLOYEE_IDastheprimarykey.Arecursiveone-to-manyrelationshipcouldbeusedtoindicatethemanagerofeachemployee.Asaresultoftherelationship,aforeignkey,sayMANAGER_ID,wouldbeusedtocross-referenceemployeeswiththeirmanagers.

DESIGNPRACTICESANDNORMALFORMNormal form is a set of rules that guide you in identifying entities andrelationships. In fact, there aremany different degrees of normal form; but inpractice, thirdnormal form is theonemost frequentlyused.For that reason, Ilimit the discussion here to third normal form. If you are interested in othernormalforms,IrecommendDate(2003).

Toqualifyforthirdnormalform,entitiesmustsatisfythreeconditions:

Allrepeatingattributegroupsshouldberemovedandplacedinaseparateentity.Allnon-keyattributesshouldbedependentonlyontheprimarykey.Allnon-keyattributesshouldbedependentoneveryattributeintheprimarykey.

Suppose the CUSTOMER entity has the attributes ADDRESS_LINE_1,ADDRESS_LINE_2, ADDRESS_LINE_3, and ADDRESS_LINE_4.Technically,suchanentityisn’tthirdnormalformbecauseit’sarepeatinggroupandviolatescondition1.Figure7.4aillustratestheexampleofthisbadpractice,andfigure7.4billustratesapossiblecorrection.

Figure7.4a:ViolationoftheFirstConditionofThirdNormalForm

Figure7.4b:ViolationCorrected

Suppose the ACCOUNT entity contains the attributeACCOUNT_BALANCE. This isn’t third normal form because it violatescondition2.ACCOUNT_BALANCEis fullydependentonoutstandingorders,thelineitemsonthem,andthepaymentsthathavebeenmade—itemsinotherentities.Another problemwithACCOUNT_BALANCE is that it isn’t atomic.ACCOUNT_BALANCE is computed based on previous orders and customerpayments.SinceACCOUNT_BALANCEiscompletelyderived,itshouldn’tbephysicallystoredandinthedatamodel.

Suppose the CUSTOMER_ORDER entity (which has a primary key thatcombinesACCOUNT_NUMBER and ORDER_NUMBER), has the attributesACCOUNT_NAME and ADDRESS_INFORMATION. This technically isn’tthird normal form because these attributes relate to the account but not thespecific order, which violates condition 3. Figure 7.5a illustrates the orderviolatingthirdnormalform,andfigure7.5billustratesacorrectedversion.

Figure7.5a:ViolationoftheThirdConditionofThirdNormalForm

Figure7.5b:ViolationCorrected

In theearlydaysof relationaldatabases, thirdnormal formwasconsideredinefficient, and “denormalization” in the name of performance wascommonplace. Despite decades of technological advancement, there are asurprisinglyhighpercentageofdeveloperswhostillsubscribeto this idea.Theusual reason given is that joins (which occur more often in a normalizeddatabase)areinefficient.

Themainside-effectofdenormalizationistheadditionalcodeandprocessingneeded to keep all copied and derived data synchronized on update. In theexample above, if you include account information on the customer order to“denormalize”andeliminatetheneedforqueriestojoinbetweenthetwotables,then you’ve effectively copied the account information once per order.Whenthataccountinformationchanges,itmustbechangedontheordersaswell.

Thesedays,joinsareefficient,anddenormalizationsshouldbearareevent.If you want to make queries easier for support developers who write ad hocqueries to investigate defect reports, then create a series of views for thatpurpose.

CREATINGDATABASESCHEMADEFINITIONSTypically, database administrators use the data model to create relationaldatabase schemas for the rest of the team to use. And most databaseadministratorsusemodelingtoolstodothedirtywork.Unfortunately,fewopensource tools for creating schemas are available. Although the process is a bitmoreinvolvedthanwhatIillustrateinthissection;withthehelpofaqualifieddatabase administrator, you can create schemas using the following centralalgorithm:

1. Directlytranslateeachentityintoatable.Allattributesofanentitybecomecolumnsinthetable.Explicitlydefinetheprimarykeyineachtable.

2. Assignaforeignkeyinthechildentityofeachone-to-manyrelationship.Remember,aforeignkeyistheprimarykeyofanotherentitythatexistssothatyoucanmatchdatainoneentitytoanother.Forexample,CUSTOMER_IDwillappearasaforeignkeyintheACCOUNTtablesothatyouhaveawaytoassociateanaccountwithaspecificcustomerusinganSQLjoin.It’sagoodideatoindexallforeignkeystofacilitatequeryjoins.

3. Rewriteeachmany-to-manyrelationshipbyaddinganassociativetableandtwoone-to-manyrelationships.Anassociativetablehasaprimarykeythatismadeupoftwoforeignkeys.Forexample,lookbackatfigure7.2toseethemany-to-manyrelationshipbetweenCUSTOMERandPRODUCT.Thiswillgetimplementedbycreatinganewtable(calledCUSTOMER_LINE_ITEM,forexample)thatrelatescustomerstoproducts.

COMMONDATABASEDESIGNMISTAKESDenormalizing the database out of habit. Denormalizing a database meansreplicating information to avoid lookups and enhance performance.Consequently,denormalizationcanintroducemaintenanceproblemsifthecopiesgetoutofsynch.

In the early days of relational databases, denormalization for performancewas amust.However, the technology has advanced to the pointwhere forceddenormalizationsare rare.Today,denormalizationsaredonemoreoutof (bad)habitthanforperformancereasons.

Dropping database integrity constraints for programmatic convenience.Somedevelopers like to shut off the foreign key relationships between tables.Not using database integrity constraints initially saves the programmer timebecauseitpermitsinvalidinserts,updates,anddeletes.ButI’vefoundyoulosemuchmoretimethanyousavebecauseyouenduphavingtofightbugscreatedbyflawedinserts,updates,anddeletes.Thesooneryoucatchabug,thecheaperandeasieritistofix.

Attempting to use relational data modeling concepts to design NoSQLdatabases. The data modeling concepts described in this chapter apply torelational databases only. Most NoSQL database products aren’t designed tosupport the wide variety of queries and relationships within the data that

relationaldatabasesaredesignedtohandle.

IMPROVINGYOURDATAMODELINGSKILLSGet a mentor. Choose someone whose data modeling skills you respect toreviewyourmodelsforcurrentassignments.Often,someoneoutsidetheprojectcanprovideamoreobjectiveviewpoint.Thiscanbedoneprivatelyunlessyourmanagerrequestsotherwise.

Audit relational databases for applications you support.Whatmistakes doyou see? Are there any violations of third normal form? Is there anydenormalization or data duplication present? Is there anything here that youwould have modeled differently if you were given the chance? Take note oftheseitems.Youmaynotget theopportunity tofix themistakes thatyoufind,butyoumightbeabletoavoidmakingthesamemistakesonfutureassignments.

CREATINGXMLDOCUMENTFORMATSInadditiontotheiruseindatabasedesign,data-modelingtechniquescaneasilybeapplied todesigningXMLdocuments.The samedatamodels thatdatabaseadministratorsusetocreatephysicaldatabasedesignsalsoreadilytranslateintoXMLdocumentformats,suchasDTDsorschemas.XMLismostoftenusedasameansofcommunicationbetweenapplications.

The first step in creating any XML document is to identify the documentroot.XMLdocumentsusuallycontainlistsofthingsidentifiedinthedatamodel.For instance, a<customer-update>documentmight containa listof customer-relatedelementsthatcontaininformationthathaschanged.A<purchase-order>documentmightcontainalistoforder-relatedelementsdescribingoneormorepurchaseordercontents.

Entities inadatamodel translate to elements inanXMLdocument.Onlyimplement the elements that are needed for the documents you’re creating.Chancesarethatyoudon’tneedallentitiestranslatedintoelements.Entitiesthatrepresent small lookup value domains (e.g., CUSTOMER_TYPE,ACCOUNT_TYPE, etc.) are usually implemented as attributes rather thanelementsinanXMLdocument.

Attributesofanentitybecomeattributesofthecorrespondingelement.Forexample, the <customer> element from figure 7.1 would have the attributes

customer-id,last-name,first-name,andtelephone.

Aone-to-manyrelationshipimpliesthatoneelementisthechildofanotherinanXMLdocument.Unlikerelationaldatabases,aforeignkeytotheparentelement isn’t needed because it’s indicated by segment ancestry. Ancestry isindicated naturally within the XML syntax. For example, the <customer>elementfromfigure7.1wouldhaveanoptional<account>childelement.

Asamorecomplete illustration, listing7.1 isa sampleXMLdocument forthedatamodelinfigure7.1.

Listing7.1:XMLDocumentExample

<?xmlversion=”1.0”encoding=”UTF-8”?><customer-update><customercustomer-id=”C123”first-name=”Derek”last-name=”Ashmore”telephone=”999-990-9999”><accountaccount-id=”A1”account-name=”PersonalChecking”account-type=”checking”/>

</customer></customer-update>

As we normally describe XML formats in terms of schemas these days,listing7.2containsanXMLschemaforthedocumentwe’vebeendiscussing.

Listing7.2:XMLSchemaExample

<?xmlversion=”1.0”encoding=”UTF-8”?><schemaxmlns=”http://www.w3.org/2001/XMLSchema”xmlns:tns=”http://www.example.org/foo/”targetNamespace=”http://www.example.org/foo/”><complexTypename=”CustomerType”><sequence><elementname=”account”type=”tns:AccountType”></element></sequence>

<attributename=”customer-id”type=”string”></attribute><attributename=”first-name”type=”string”></attribute><attributename=”last-name”type=”string”></attribute><attributename=”telephone”type=”string”></attribute></complexType>

<complexTypename=”AccountType”><attributename=”accout-id”type=”string”></attribute><attributename=”account-name”

type=”string”></attribute><attributename=”account-type”type=”string”></attribute></complexType>

<complexTypename=”CustomerListType”><sequence><elementname=”customer”type=”tns:CustomerType”></element></sequence>

</complexType><elementname=”customer-update”type=”tns:CustomerListType”></element></schema>Rewrite all many-to-many relationships by choosing one of the entities of

eachrelationshiptobeachildelement.Forexample,consideramany-to-manyrelationshipbetweencustomerordersandproducts.This relationshipwouldberewritten as two one-to-many relationships using the entityORDER_LINE_ITEMasacross-reference.An<order-line-item>elementcouldbeachildofthe<order>or<product>element,orboth.Chancesarethatbothdonotneedtobeimplementedandthat<order-line-item>wouldbeconsideredachildof<order>.

COMMONXMLDESIGNMISTAKESDeclaring attributes as elements. One of the most common XML designmistakesIseeismakingdataelementsthatshouldbeattributes.Forexample,inlisting 7.1, some developers would have made “account-name” a separateelement insteadofanattributeof<account>.Misusingelements in thisway islikelytocauselowerparsingperformanceandslowerXSLTtransformations.

FURTHERREADINGDate,C.J.2003.AnIntroductiontoDatabaseSystems,8thed.Boston:Pearson/Addison-Wesley.

Fleming,CandaceC.,andBarbaravonHalle.1989.HandbookofRelationalDatabaseDesign.Reading,MA:Addison-Wesley.

CHAPTER8

PLANNINGCONSTRUCTION

Okay,you’vereadthechaptertitleandyou’rethinking,“What’sachapteronprojectplanningdoinginanapplicationarchitect’shandbook?”Butremember:partoftheapplicationarchitect’sroleistogivetheprojectmanagerinformationon construction tasks, the order inwhich they should be completed, andwhatdependenciesexist.Andthesedays,applicationarchitectsareoftencalledontoassistorevenfulfilltheprojectmanagementrole.

This chapter is included for those in organizations using non-agilemethodologies for which project planning is more relevant. Most agilemethodologiesrelyonteamstobeself-managing;hence,projectplanningattheleveldescribedinthischapterdoesn’tusuallytakeplace.

This chapter develops, and adds detail to, the high-level requirementsdescribed inchapter3.Aftercompletinguse-caseanalysisandobjectanddatamodeling, you should have enough information for amore detailed plan.Myprojectplanstypicallyincludethefollowingtypesofactivities:

BusinessrequirementsgatheringTechnicaldesignDatabasedesignEnvironmentsetupProjectsetupDatamigration/conversionactivitiesCodingandunittestingSystemtestingPerformance/loadtestingUseracceptancetestingDeploymentactivities

Manyofthesecategoriescanbedividedintolower-leveltasks.Forexample,you could breakdown “business requirements gathering” into prototyping anduse-case analysis activities. Typically, I divide “coding and unit-testing”activitiesintosmallersectionsthatcanbeassignedtoindividualdevelopers.

Some of these categories are applicable only to the development of newapplications,asopposedtoenhancementsofexistingapplications.Forexample,newapplicationslikelyneedtasksfor“environmentsetup”and“projectsetup,”whereasinmostcases,existingapplicationsalreadyhavetheseandtheyarenotneededforprojectsenhancingexistingapplications.

Figure8.1showsatemplateprojectplanIuseforJavaEEwebapplications.Tasks are listed roughly in completion order. I use the open source productOpenProj(http://sourceforge.net/projects/openproj/).

Figure8.1:JavaEEWebApplicationProjectPlanTemplate

TaskName Work

J2EEApplicationDevelopment

BusinessRequirements

Prototypes

Prototype1 8hours

Prototype2 8hours

Prototype3 8hours

PrototypePresentation1 8hours

PrototypePresentation2 8hours

UseCases

UseCase1 8hours

UseCase2 8hours

TechnicalDesign

DatabaseDesign/DataModeling 16hours

Third-partyProductResearch 16hours

ObjectModeling 16hours

ProcessFlows 16hours

EnvironmentSetup

ProjectSetup

SourceControlRepositorySetup 4hours

DevelopmentBuildScript 4hours

ContinuousIntegrationSetup 4hours

DeploymentSetup

DevelopmentDatabase 8hours

SystemTest 8hours

UserAcceptanceTest 8hours

Production 8hours

CodingandUnitTestingTasks

EntityClasses 8hours

DataAccessObjectClasses

DAO1 16hours

DAO2 16hours

BusinessLogicLayerClasses

Logic1 16hours

Logic2 16hours

PresentationGUI

Section1 16hours

Section2 16hours

BatchJobsandWebServices

Job1 8hours

Job2 8hours

SystemTestingActivities 8hours

UserAcceptanceTestSupport 8hours

It’spossible thatsomeof the taskspresented inmytemplatedon’tapply tosome projects. For instance, if the project is an enhancement to an existingapplication,theprojectandenvironmentsetuptasksmaynotbeneeded,astheyalreadyexist.

TASKORDERANDDEPENDENCIESThe most common planning question I get from project managers is how toeffectively order construction and unit testing. I usually advise the followingorder:

DAO(withtestingclasses)andentityclassesBusinessobjects(withtestingclasses)PresentationlayerBatchjobs,webservices,andapplicationinterfaces

Architecturalcomponentsofaprojectneedtobeconstructedbeforetheyareneeded. There is no way to make more detailed recommendations forarchitecturalcomponentsbecausetheycanbeusedinalllayersoftheproject.

YouwillfindthatmostbusinessobjectsrelyheavilyonDAOsandentities.As such,youcannot completemostbusinessobjectsuntil theclasses theyusearecomplete. Ifyou’reusingprojectmanagementsoftware,youshouldensurethatthesedependenciesareproperlyreflectedintheplan.

Thepresentation layeractionsandJSPswould logicallybecompletedafterthedeploymentlayeriscoded.Ifthepresentationlayercodingandconstructionmust start first forpolitical reasons, then stub thebusiness logic classes; these“stubs”arethrowawaywork.

The tasks at this point in the project should become granular enough thatmost developers will feel comfortable providing estimates. As a result, theprojectplancanbemoreaccuratenowthaninthepreliminarystagesdescribedinchapter3.

If you’re using a project management tool, and the work schedule itcomputesdoesn’tmakesense, themost likelycause is thatsomedependenciesare incorrect or missing. Many people circumvent the management tool andmanuallycomputeandenterstartandenddatesforallthetasks.Iprefertofixthedependenciesratherthanproduceanunrealisticplan.

Anotherconsiderationisprojectrisk.Ifthereareportionsoftheapplicationthatpresentmorerisk,thosetasksshouldbecompletedassoonaspossible.Forexample, if you’re using an unfamiliar technology, it’s possible that you willencounter unexpected difficulties. Completing these tasks upfront gives youmoretimetoreactshouldproblemsarise,withlessimpactonthetotalproject.

CriticalPathThecriticalpathisasetofdependenttasksthatmustcompleteontimefortheprojecttocompleteontime.Ineffect,thecriticalpathdeterminesthelengthoftheproject.Adelayofonedaytoataskinthecriticalpathwilldelaytheprojectbyoneday.Conversely,onedaysavedinthecriticalpathmayallowtheprojectto come in one day early. Let’s use an example everybody can relate to: I’mdoing laundry on the side as I write this. My laundry project isn’t software-related, but all of the concepts are exactly the same. It takesme about ninetyminutestodooneloadoflaundry:thirtyminutestowash,fiftyminutestodry,andtenminutestofold.IfIonlyneedtodooneload,allthreetasksareonthecritical path.Everyminute I delay transferring clothes from thewasher to thedryerisaminuteIaddtotheentireproject.

Sometimes,notall tasks in theproject areon thecriticalpath.Noncritical-path taskscanusuallybedelayedor rescheduledwithout impact to theprojectcompletion time. Suppose I need to do two loads of laundry (and I have onewasherandonedryer)andwishtocompletetheprojectin120minutes.Thefirstwash ison thecriticalpath,but thesecondwash isn’t. Icouldstart thesecondwashimmediatelyafter transferringthefirst loadfromthewashertothedryer,but I don’t have to. I can safelywait twentyminutes to start the secondwashwithoutaffectingtheprojectendtime,asthedryertakestwentyminuteslongerthan thewasher. In this example, the firstwash load, both dry loads, and thefoldingofthesecondloadareonthecriticalpath.

If you’re an application architect doubling as a projectmanager, paymoreattention to the critical path than to anything else. Most project managementsoftwarepackageshighlightthecriticalpathifyouhaveenteredalltheresourceassignmentsanddependenciescompletely.

Thecorollary is that timesavedonnoncriticalpath taskswillnotallowtheproject to finish earlier. The reason is that those tasks aren’t currentlydetermining theproject timeline; criticalpath tasksare.Furthermore, a criticalpathcanshift; that is, tasksonthecriticalpathcanchangeifyourprojectplanchanges.Ifyousaveenoughtimeonacriticalpathtask,it’spossiblethatitisn’tonthecriticalpathanymore—somethingelseis.Ifalongdelayoccursforataskthatisnotonthecriticalpathbutisstillessential,thetaskmightbecomepartofthecriticalpath.

For example, financial analysis software I helped develop included acomponent responsible for generating analysis, using company financialinformation and financial models that users input. In the beginning, this

componentwas not part of the critical path.But as the project proceeded, thecritical path changed to incorporate the component because the developerleading theeffort towrite itdidn’thaveenoughknowledgeandexperienceforthetask.

ThebestbooksI’veencounteredontheimportanceofthecriticalpath(andplanning in general) are by Goldratt (1992, 1997). Although both books usefactory assembly lines as examples, the concepts are applicable to Java EEprojects(andwiththeirnovel-likeformat,thebooksareentertainingreads).

COMMONMISTAKESGoingstraighttocode.Manydevelopersareimpatientwithdesign.Theyviewobject-modelinganddata-modelingactivities asboringcomparedwith coding.I’ve seenmany projects proceed to codingwithout doing enoughmodeling tofirst figure out what the target is. Althoughmost of those projects eventuallywere finished, they typically used more resources than was necessary.Sometimes,targetlesseffortscanusetwotofourtimestherequiredresources.

Agood analogy is residential construction.When contractors build houses,they create the blueprints first to avoid costly mistakes and rework. ObjectmodelsanddatamodelsareeffectivelyblueprintsforJavaEEapplications.

Permittingamovingtarget.Oncescopeisdecidedfortheproject(e.g.,ithasbeendecidedwhichusecaseswillbeimplemented,andthecontentofthoseusecaseshasenoughdetailfromwhichtodesign),discourageorevenoutlawscopeincreases. I know this is easier said than done. McConnell (1998) suggestsinstalling a change control board, which is charged with reviewing andauthorizing all change requests once a project has progressed passed analysisand high-level design. The existence of a change control board effectivelydiscouragesscopeincreasesbycreatingbureaucraticredtape.

Ifyoucan’tavoidaddingsomethingtoaprojectlateinthegame,makesuretheadditionalactivities,time,andcostsgetaddedtotheprojectplan.Also,makesurethattherevisedprojectplanreflectsthefactthatthetimespentonanalysisanddesignforthenewfeatureszappedtimefromwhatyouweresupposedtobedoing (making it late too). If the new feature causes rework on tasks alreadycompleted,makesurethatthosecostsarealsodocumentedforalltosee.

Think of the residential construction analogy again. Changes in what thehomebuyerwantscausereworkandimpactthedeliverydate.

Not correctingpersonnel assignmentmistakes.Of course, it’s best to avoidmakingmistakesinthefirstplace.Butwhenmistakeshappen,yourbestcourseof action is to recognize and fix them rather than ignore them. The mostdamaging mistakes in large projects are in the areas of personnel taskassignment. This type of mistake is so damaging because most managers areunabletogatherthecouragetocorrectthemistakesandthereforeallowthemtocontinue.

Although the project manager traditionally handles personnel assignments,thearchitect(withmoreknowledgeoftechnicalskillsets)shouldatleastbeinan advisory role. DeMarco and Lister (1999) make some interestingobservations:

Countonthebestpeopleoutperformingtheworstbyabout10:1.Countonthebestperformerbeingabout2.5timesbetterthanthemedian.

In addition, people generally are extremelygood at some tasksbut poor atothers. Good project managers learn to recognize the differences and adjustassignments appropriately. For example, someone might be a whiz when itcomestocodingthepresentationtierbutacompletedudatcodingarchitecturalcomponents.Somepeoplecanperformtestingwitheasebutarepooratcoding.

Savingintegrationtestingactivitiesuntiltheendoftheproject.Analysisanddesign mistakes and omissions often aren’t visible until construction begins.Integration testing the applicationmakes analysis and designmistakes visible,eveniftheapplicationisonlypartiallyfunctional.Findingthesemistakesearlierin theprojectgivesyouachance tocorrect theerrorwith fewereffects to theprojecttimeline.

IMPROVINGYOURPROJECTPLANSANDESTIMATESTrackyourtime.Itisimportanttotrackyourtimeinsuchawaythatyoucaneasily map that time to specific tasks you’ve been given. If you lead otherdevelopers, have them track their time as well. It is also important that youestimatethetimeitwilltakeyoutocompleteataskbeforeyoucompleteitandmeasurethetimeyouspenddoingit.Thetimeyouestimatewillrarelyequalthetimethatyouspent.Withthisprocess,you’llbeabletobeginunderstandinghow

close your estimates are to reality. Over time, you will notice the differencebetweenyourestimatesandthetimethatyouspendgetsmaller.

Don’t discard estimates and time tracking records frompast assignmentsandprojects.Whenyouneedestimates for futureprojectsorassignments, it’shelpfultolookatcomparableassignmentsorprojectsthatyouhavedoneinthepast.Thisissimilartohowrealestateagentsdecideifthepriceofapropertyistoo high or low; they look for recently sold properties similar to it and checktheirsellingprices.

Have a colleague review your estimates. Someone not involved with theprojectmayeasilyseethingsthatyouhavemissed.

FURTHERREADINGDeMarco,Tom,andTimothyLister.1999.Peopleware:ProductiveProjectsandTeams,2nded.NewYork:DorsetHouse.

Goldratt,Eliyahu.1992.TheGoal:AProcessofOngoingImprovement.GreatBarrington,MA:NorthRiverPress.

———.1997.CriticalChain.GreatBarrington,MA:NorthRiverPress.

McConnell,Steve.1998.SoftwareProjectSurvivalGuide.Redmond,WA:MicrosoftPress.

SECTIONIII

BUILDINGJAVAEEAPPLICATIONS

Once thedesign iscomplete, theapplicationarchitect isoftenasked toguideapplication construction. Activities that are the direct responsibility of theapplication architect during construction include setting coding standards;mentoring junior developers through more difficult programming tasks; andestablishing conventions for logging, exception handling, and applicationconfiguration. In addition, the architect (or senior developer) is usuallyresponsible for coding any custom architectural components the applicationrequiresbecauseofthedifficultyinvolvedinthetask.

Thissectionguidesyouthroughtheapplicationconstructionprocess.Init,youwilllearnhowto:

Establishcodingconventionsforallsoftwarelayers.Chooseadatabasepersistencemethod(e.g.,JDBC,JPA,etc.).Setconventionsandguidelinesfortransactionmanagement.Understandhowtomakearchitecturalcomponentseasyfordeveloperstouse.Setguidelinesforlogging,exceptionhandling,threading,andconfigurationmanagement.

The first edition of this book relied on an open source product calledCementJ (http://sourceforge.net/projects/cementj/), which was provided as ashortcutforimplementingthelayeringconceptspresentedinthisbook.CementJalsoprovidednumerous time-savingstaticutilities that turnedcommoncodingtasksintoone-liners.CementJisnowobsolete.

Sincethattime,numerousopensourceprojectshavematuredtoprovidethisfunctionalityinamorerobustway.Consequently,CementJhasbeenreplacedby

several common open source projects from the Apache Commons(http://commons.apache.org/)familyofprojectsincluding:

ApacheCommonsLang(http://commons.apache.org/lang/)ApacheCommonsCollections(http://commons.apache.org/collections/)ApacheCommonsBeanUtils(http://commons.apache.org/beanutils/)ApacheCommonsDbUtils(http://commons.apache.org/dbutils/)ApacheCommonsIO(http://commons.apache.org/io)GoogleGuavaCoreLibraries(https://code.google.com/p/guava-libraries/)

CHAPTER9

CODINGVALUEOBJECTSANDENTITIES

Justasvalueobjects(VO)andentitiesaresimilarinthattheycombinelogicalgroups of data items into a single logical construct; the coding standards andguidance for them are similar in many ways. The largest difference betweenthemisthatentityclasseshaveamaptoadatabasetableandarepersisted,whileVOclassesare transient innature. In theearlydaysof JavaEE,valueobjectswereusedtominimizenetworktransmissionbetweenenterprisebeansandtheirremote callers. As the use of enterprise beans has declined—since in manyapplications it is an unnecessary complexity—this purpose for value objectclasseshasbeenreduced.

Atfirstglance,mybroaderdefinitionofavalueobjectorentityclassappearstocontradicttheprinciplesofobject-orienteddesignthattellustocombinedatawith the business logic. Object orientation principles would have us think of“employee”asanobject thatcontains itsdata (e.g., lastname, firstname)andmethodslikeadd(),terminate(),andoppress()thatrepresentbusinesslogic.Formanypracticalconsiderations,suchasreducingcomplexity,weneedtohavetheoptionforreferencingdataoutsidethebusinesslogiccontext.

Chapter11willshowyouwaysofconstructingobjectsinthebusinesslogiclayer that adhere to object-oriented design principles and also allow you toreference the data portionof these objects as a value object. For example, theEmployeeclasscouldeasilyprovideagetEmployeeVO()accessorthatprovidesthedataforanemployeewithoutitsbusinesslogic.

Figure9.1:UsingValueObjectsandEntitieswithinaLayeredArchitecture

Because the application architect is responsible for establishing codingstandards and guidelines and for mentoring development staff, this chapterprovides several implementation tips and techniques for value objects andentities. Additionally, the chapter explains several concepts needed foreffectively structuring value objects and entities. And to make implementingthese recommendations easier and less time consuming, the chapter presents abase value object class, which I’ve included in the source bundle(j2ee.architect.handbook.common.BaseVO).Aswewilldiscuss,it’smuchmoredifficultanddangeroustoprovidesuchabaseclassforentities.

IMPLEMENTATIONTIPSANDTECHNIQUESAlwaysimplementjava.io.Serializable.Foravalueobjectorentitytobeusableasanargumenttoanytypeofdistributedobject,suchasenterprisebeansorRMIservices, itneeds to implementSerializable.Therearenomethods requiredbySerializable,soimplementationiseasy.You’rebetteroffnotputtinganything—suchasadatabaseconnection—inavalueobject that isn’t serializable.But ifyoumustputanon-serializableobject inavalueobject,declare it transient soit’sbypassedduringanyserializationattempts.Listing9.1isanextractofvalueobjectcode.

Listing9.1:SampleValueObjectCodepublicclassSalesSummaryVOimplementsSerializable,Comparable<SalesSummaryVO>{

privatestaticfinallongserialVersionUID=-4099990023592442788L;privateStringsalesRegion;privateIntegersalesYear;

privateDoublesalesQuarter1;privateDoublesalesQuarter2;privateDoublesalesQuarter3;privateDoublesalesQuarter4;//Codesuppressedforbrevity

}

Source:srcj2ee/architect/handbook/chap09/sample1/SalesSummaryVO.javaAlwayspopulateall fieldsofavalueobjectorentity.Someprogrammers,forthesakeofconvenience,don’ttakethetroubletopopulateall fieldsofavalueobjectorentity if theyonlyneeda subsetof the fields in it.This is less likelywithentitiesastheyusuallyarepopulatedbytheJPAimplementation.Inmyexperience,thispracticesavestimeduringconstruction,but it inevitablycausesbugs thatshowupasNullPointerExceptionexceptionswhensomethingattemptstouseafieldthatisnotpopulated.Furthermore,partialpopulationofavalueobjectorentitycreatesaninconsistencythatdeveloperswillfindconfusing.Irecommendeitherpopulatingallfieldsofavalueobjectorcreatinganewvalueobjectwiththenewfieldset.

Always type fields accurately. I’ve often seen programmers implement datesandnumbersasstrings,usuallytosavetimewheninitiallycodingavalueobjectorentity.Themotivationforthisisfacilitatingdisplayorthecodingofaspecificprocess.Butastheapplicationgetslarger,thispracticecancauseconfusionandinevitably results inadditionalconversioncodewhere the field isused. It alsoleads to confusion for maintenance and causes bugs, because someone willformatthestringsinappropriately.

Checkdependenceonthird-partyclassesinvalueobjects.Valueobjectsareused as arguments for distributed objects, such as enterprise beans and RMIservices.Ifyourvalueobjectsrelyonthird-partyclasses,yourcallerswillhavetoincludethemintheirclasspathtocallyou.Thiscanbeaninconvenienceforyourcallersandmakeyourdistributedobjectshardertouse.

Always override method toString(). If you don’t override toString(), theresulting text is not very meaningful. An example from the defaultimplementationoftoString()iscom.myapp.Test@3179c3.

SincethereareenoughclassesintheJDKthatacceptObjectargumentsandexpect to be able to execute method toString(), you should provide animplementation.TheimplementationoftoString()inheritedfromObjectisn’tallthatuseful.

Consider overridingmethods equals() and hashcode(). If a value object isever used as a key in a HashMap, Hashtable, or HashSet; equals() and

hashcode() are used for key identification. The definition of these methods,inheritedfromObject,dictatesthatfortwovalueobjectstobeequal,theymustliterallybethesameclass instance.Forexample,consideraCustomerVOwithfirstNameandlastNamefields.Youcouldhavetwoinstancesof“JohnDoe”thatwill look unequal using the equals() inherited from Object. You will have tooverridebothequals()andhashcode()foravalueobjectifyouwantitusableinanytypeorMapimplementation,suchasHashtable,HashMap,orTreeMap.

Thebehavior differencesbetween ameaningful implementationof equals()and the implementation inherited fromObjectconfusesmany developers. Theexampleinlisting9.2ashouldhelpalleviateanyconfusion.

Listing9.2a:SampleObject.equals()ImplementationpublicvoidshowObjectEqualImplementation(){

ObjectWithoutEqualsImplfiveAsObject=newObjectWithoutEqualsImpl(“5”);

ObjectWithoutEqualsImplanotherFiveAsObject=newObjectWithoutEqualsImpl(“5”);

ObjectWithoutEqualsImplsevenAsObject=newObjectWithoutEqualsImpl(“7”);

System.out.println(“Objectequals()demo:”);System.out.println(“\tfiveAsObject.equals(anotherFiveAsObject):“+

fiveAsObject.equals(anotherFiveAsObject));System.out.println(“\tfiveAsObject.equals(sevenAsObject):“+

fiveAsObject.equals(sevenAsObject));

}

Source: srcj2ee/architect/handbook/chap09/sample1/EqualsDemonstration.java Listing 9.2a uses a simpleclass that does not override method equals()and uses the implementation inherited from Object. Thevariabledeclaredinline3withthevalue5shouldbe“equal”totheobjectdeclaredinline5.However,ifyouweretorunthesample,youwouldseethatthevariablesareactuallynotconsideredequal.Outputtothesampleisprovidedinlisting9.2b.

Listing9.2b:OutputfromListing9.2aObjectequals()demo:

fiveAsObject.equals(anotherFiveAsObject):falsefiveAsObject.equals(sevenAsObject):falseIfyouweretorunadifferentsampleusingclassStringinsteadofObjectWithoutEqualsImpl,theoutputwouldbemorewhatyouwouldexpectbecauseStringoverridesmethodequals().

Themethodhashcode()returnsan integer that isguaranteed tobeequalfor

two instances of Object that are equal. The logic behind constructing analgorithm to do this can get intricate. Fortunately, a good implementation ofhashcode logic has been implemented in theApache Commons Lang product(http://commons.apache.org/lang/) in class HashCodeBuilder. Listing 9.3illustratesaneffectiveimplementationofhashcode().

Listing9.3:Samplehashcode()Implementation@Override

publicinthashCode(){returnnewHashCodeBuilder(17,37).append(this.salesRegion).append(this.salesYear).append(this.salesQuarter1).append(this.salesQuarter2).append(this.salesQuarter3).append(this.salesQuarter4).toHashCode();

}

Source: srcj2ee/architect/handbook/chap09/sample1/SalesSummaryVO.java Implementing equals() issimilarinthatweonceagainutilizetheApacheCommonsLangproduct.Thisisshowninlisting9.4.

Listing9.4:Sampleequals()Implementation@Override

publicbooleanequals(Objectobj){if(obj==null){returnfalse;}if(obj==this){returntrue;}if(obj.getClass()!=getClass()){returnfalse;

}

SalesSummaryVOrhs=(SalesSummaryVO)obj;returnnewEqualsBuilder().append(this.salesRegion,rhs.salesRegion).append(this.salesYear,rhs.salesYear).append(this.salesQuarter1,rhs.salesQuarter1).append(this.salesQuarter2,rhs.salesQuarter2)

.append(this.salesQuarter3,rhs.salesQuarter3).append(this.salesQuarter4,rhs.salesQuarter4).isEquals();

}

Source: srcj2ee/architect/handbook/chap09/sample1/SalesSummaryVO.java Consider implementingjava.lang.Comparable.Ifyoueveruseavalueobjectinasortedcollection(e.g.,TreeSetorTreeMap),you

must implement Comparable for sensible sort results. Implementing Comparable requires theimplementationofacompareTo()methodthatreturns0ifthetwoobjectsareequal,anegativenumberiftheObjectislessthantheargumentpassed,andapositivenumberiftheObjectisgreaterthantheargumentpassed. Fortunately,ApacheCommons Lang comes to our assistancewith the CompareToBuilder class.Listing9.5illustratesthis.

Listing9.5:SamplecompareTo()ImplementationpublicintcompareTo(SalesSummaryVOo){

returnnewCompareToBuilder().append(this.salesYear,o.salesYear).append(this.salesRegion,o.salesRegion).append(this.salesQuarter1,o.salesQuarter1)

.append(this.salesQuarter2,o.salesQuarter2).append(this.salesQuarter3,o.salesQuarter3).append(this.salesQuarter4,o.salesQuarter4).toComparison();

}

Source:srcj2ee/architect/handbook/chap09/sample1/SalesSummaryVO.java

VALUEOBJECTSMADEEASYMy laundry list of recommendations makes implementing value objectsextremelyboring,tedious,andtimeconsuming.Asanapplicationarchitect,youhavetheoptionofmentoringdevelopersastheyfollowtheserecommendationsand, you hope, implement them consistently. Another option is to providearchitecturalutilitiesthatmakecodingvalueobjectseasierandquickerandbringsomeconsistencytovalueobjectbehavior.

ThesegoalsareachievedbyBaseVOincludedinthesourcebundle,atoolIcreatedtoprovidearchitecturalsupportforvalueobjects.IfvalueobjectsextendBaseVO, they get meaningful equals(), hashcode(), and toString(), and theyclone()implementationsautomatically.

BaseVOdoesusereflectiontoachieveitsmagic,soit’sslowerthancustom-coded value objects. Table 9.1 presents a performance comparison for oursampleSalesSummaryVO.

Table9.1:PerformanceComparisonforBaseVOfor100,000Operations(JDK1.7)

Version Millisecondsper100,000Operations

clone() toString() hashCode() equals()

VOextension 2214ms 3511ms 829ms 940ms

Custom 27ms 774ms 52ms 9ms

For the table, I arbitrarily chose 100,000 iterations to make the timedifferencesmoreapparent.Mostapplicationswillhavefewerexecutionsofthesemethodspertransaction.

By using BaseVO, you trade some performance for development andmaintenance time.Mostvalueobjects inanapplicationuse theseoperations inlargeenoughvolumeforthespeedofBaseVOtobeanissue.Irecommendyoucustomcodeonlythesmallnumberofvalueobjects thatyou’vedeterminedtoneedfasterexecutiontimebasedonyourperformance-tuningefforts.

In addition, since value objects that extend BaseVO contain only smallamountsof logic, if any;no test casesarenecessary. Ifyouchoose toprovideyourownimplementationsofequals(),hashcode(),and toString(), you need toconstructtestcasesforthesemethods.

Warning:It isdangeroustohaveentitiesextendBaseVO.Thereareseveralreasonsforthis.Entitiesareoftenrelatedtootherentities.Whenyoureferencethem, queries are issued under the covers to find related entity instances. Forexample, a customer may have many accounts. When BaseVO formulates atoString()valueusingreflection,itwillaccessallaccountsandinitiateaquerytofind that information. Thiswouldmake the generic implementations found inBaseVOextremelyexpensiveforentities.

COMMONMISTAKESPopulating VOs inconsistently. I’ve seen some applications where fields ofvalue objects were populated with different value sets depending on usagecontext.Forexample,consideraCustomerVOwithname,address,contact,andseveral other fields. I’ve seen developers use a structure like this, but onlypopulate name and address in a specific section of code as that was all thatsectionofcodeneeded.Thiscancausedeveloperconfusionandbugs,asotherfieldsarepresentbutcan’tbereliedoninthissectionofcodetohavedata.Toeliminateconfusion,itwouldhavebeenbettertocreateaseparatevalueobjectwithonly the fieldsused in thatsectionofcode.Usually, thispractice isa redflagindicatingthatthedesignisprocessorientedinsteadofobjectoriented.

Using a blank string to avoid a NullPointerException. Some developersinitialize all fields to a blank string or something thatmeans “null” but reallyisn’t,asinthefollowing:privateString_customerName=“”;

Although this kind of declaration eliminates NullPointerExceptionexceptions, it doesn’t prevent some other type of derivative exception fromappearingdowntheline.Thispracticeisakinto“sweepingdirtundertherug”and is best avoided.Furthermore, this kindof sweeping isn’t necessary if youadoptthepracticeofvalidatingallargumentsforprotectedandpublicmethodsupfrontastheerrormessagereceivedwillbeexplicit.

EmbeddingformattingassumptionsintoentitiesorVOs.Forexample,somedeveloperswill return strings that represent dates or numbers as that’swhat’sdisplayed in the presentation layer. Unfortunately, it limits reusability for theentityorVOasthepresentationformatdesiredfordifferentapplicationsorevenportions of an application will likely differ. This is really a violation of theseparation of concerns principle in that the entity or VO is given displayresponsibilities as well as data retention responsibilities. Keep formattingconcernsinthepresentationlayer.

It shouldbenoted that representingdate and timeas anythingother thanajava.util.Date is also an example of embedding formatting assumptions. Forexample, some developers use java.sql.Date or java.sql.Timestamp in VOs orentities;theseclasseswrapjava.util.DateforpurposescloselytiedtoJDBCanddatabasestorage.Keeptheseformattingconcernsinthedataaccesslayer,whichbydefinitionneedstoconcernitselfwithstorageissues.

Maintaining parent-child relationships for VOs or entities in bothdirections. For example, the CustomerEntity would contain a collection ofAccountEntitychildren,andeachoftheAccountEntityinstanceswouldcontainareferencebacktotheparent.Yourunintothesameproblemswiththispracticeasyoudowhenyoureplicatedata in relationaldatabases.The result isdoublethemaintenancewhendata ischanged.Further, thepractice iserrorproneandtendstobetherootcauseofbugs,includingmemoryleaks.

EXAMPLE:ADMIN4JAdmin4J(www.admin4j.net)isanopensourceproductthatprovidesbasicJavaEE application administration and support features for support developers.Admin4J has several value objects that are used to facilitate user information

display.As suggested in this chapter, all value objects extend BaseVO and have

meaningful toString(), equals(), hashCode(), and clone() implementations. AnexamplevalueobjectextendingBaseVOcanbefoundinlisting9.5.

Listing9.6:PerformanceSummaryVOValueObjectfromAdmin4J

Source:Admin4Jsourcecodedistribution(www.admin4j.net)

Asdiscussed, thisvalueobjectreliesonabasevalueobjectclassprovidingmeaningful implementations of toString(), equals(), hashCode(), and clone().Sourceforthisclasscanbefoundinlisting9.6.

Listing9.7:BaseVOValueObjectfromAdmin4J

Source:Admin4Jsourcecodedistribution(www.admin4j.net)

NoticethattheBaseVOclassleveragesvariousbuilderclassesfromApacheCommonsLang.

Some of Admin4J’s value objects have custom overrides for equals() andhashCode()forperformance.Forexample,avalueobjectclassFileWrapperVOhas custom overrides for both equals() and hashCode(). Listing 9.7 containssourceforbothoverrides.

Listing9.8:FileWrapperVOValueObjectOverridesforequals()andhashCode()

Source:Admin4Jsourcecodedistribution(www.admin4j.net)

DIFFERENCESFROMTHEFIRSTEDITIONThe first edition of this book introduced a technique for having value objectsprovideatextualdescriptionofthemselvesforerror-loggingpurposes.Thiswasachieved by having value objects implement an interface Describable. Theobjectivewastostandardizedescriptionsincludedwithexceptionsinawaythatreducedtheprobabilityoferringoutformattingthetextofanexception.

Today, there is a much better and less invasive way of accomplishing thesame goal.With version 3.0 ofApacheCommonsLang, two exceptionswereintroduced: ContextedException and ContextedRuntimeException, which Icontributed. These exceptions make it easy and safe to include additional

informationwiththrownexceptionswithoutfearofaccidentallyexceptingintheformattingofanerrormessage.Asyoumighthaveguessed,ContextedExceptionischecked;ContextedRuntimeExceptionisnot.

Anexampleofhowtousetheseexceptionscanbefoundinlisting9.8.

Listing9.9:ExampleofContextedRuntimeExceptionUsagetry{

...}catch(Exceptione){thrownewContextedRuntimeException(“Errorpostingaccounttransaction”,e)

.addContextValue(“AccountNumber”,accountNumber).addContextValue(“AmountPosted”,amountPosted).addContextValue(“PreviousBalance”,previousBalance)}

Thisexamplewillproduceamessagesimilartothatinlisting9.9.

Listing9.10:ExampleofContextedRuntimeExceptionOutputorg.apache.commons.lang3.exception.ContextedRuntimeException:java.lang.Exception:ErrorpostingaccounttransactionExceptionContext:

[1:AccountNumber=null][2:AmountPosted=100.00][3:PreviousBalance=-2.17]

---------------------------------

atorg.apache.commons.lang3.exception.ContextedRuntimeExceptionTest.testAddValue(ContextedExceptionTest.java:88).....(restoftrace)

ThecontextedexceptionsarenullsafeandwilleventraperrorsproducedbyafaultyvaluehavingatoString()implementationthatexcepts.

CHAPTER10

BUILDINGDATAACCESSOBJECTS

Data access objects read and write saved data and convert that format toentities usable by other layers in the application. You can think of them as“factory” classes for entities. For example, CustomerDAO, a DAO in apurchasing application, reads customer information from a database or someother form of saved storage and converts that information to entities (e.g.,CustomerEntity)thattherestoftheapplicationcanuse.CustomerDAOalsousesinformation inCustomerEntity to update or insert data in the database or file.The following are some methods CustomerDAO might have: publicCustomerEntityfindById(LongcustomerId);publicvoidsaveOrUpdate(CustomerEntitycustomer);publicvoiddelete(LongcustomerId);publicList<CustomerEntity>findByPartialName(Stringname);Alllogicthatinterpretsandprocessesthat

dataisinthebusinesslogiclayer,notinthedataaccessobjectlayer.TheDAOmerelyhandlestheI/O.ItshouldbenotedthatwhilemostclassesintheDAOwilltargetrelationaldatabases,anyformofpersistentstorageshouldbemanagedatthedataaccesslayer.Inotherwords,accesstoNoSQLdatabasesshouldresideinthedataaccesslayeraswell.Thereareseveralreasonsforsegregatingdataaccess.

First,itpromotesreuse.Forexample,theremightbeseveralusecasesinanapplication that need to read and process purchase order information.Segregating data access makes the example DAO usable for all of thoseprocesses.

Second,togetherwithyourpackagestructure(whichseparatesDAOclassesinto a separate package) it allows developers to quickly find data access thatmightneedtobechangedorenhanced.

Third,itfacilitateschangingyourmethodofstoragewithoutaffectingotherparts of the application. For example, one ofmy clientsmigrated from usingSybase to Oracle. The migration was relatively easy in applications withsegregateddata access.Further, fromamaintenance standpoint, itwas easy tolocate, modify, and enhance the data access object layer to handle minorchanges,suchascolumnadditions.

Figure10.1IllustratestheRoleofDAOsintheSoftwareLayerHierarchy

MostDAOclassesinmostapplicationsarerelationaldatabaseDAOs;thatis,theyreadandwritedatausingrelationaldatabasessuchasOracleorMicrosoftSQLServer.IfyourapplicationusesaJPAimplementationlikeHibernate,DAOclasses iswhere you’ll findHibernate-dependent code. Ideally, other layers oftheapplication(e.g.,businesslogiclayer)willneverreferenceHibernateclasses.If your application uses JDBC,DAO classes iswhere you’ll find any and allreferencestoJDBCclasses.

TRANSACTIONMANAGEMENTSTRATEGIESAll Java EE applications need a transaction management strategy. That is, astrategy that defines when commits and rollbacks are issued. There are threegeneral strategies available: Servlet Filter strategy, Aspect-OrientedProgramming(AOP)strategy,andAutocommitstrategy.

TheServletFilterstrategyusesaServletfilter,whichisexecutedonallwebtransactionstoissueallcommitsforsuccessfultransactionsandrollbacksforalltransactions that except.Listing10.1containsa short exampleof this strategy.Notethatinthisexample,classTransactionContextretainsthecurrentHibernatesession and makes it available to classes in the data access layer. A similarpatterncouldeasilybeusedtoretainnativeJDBCconnectionsshouldaJDBCpersistencestrategybeused.

Listing10.1:SampleTransactionManagementFilterLogic

Source:srcj2ee/architect/handbook/chap10/TransactionManagementFilter.java

The AOP strategy uses aspect-oriented technologies, such as AspectJ(http://www.eclipse.org/aspectj/), to surround methods in data access classeswithcommitandrollbacklogic.Often,thisapproachistoogranulartobeuseful.While one can address the granularity issue and take the time to plan whichclassesare targeted for transactionmanagement, this can lead toconfusion fordevelopers. It is not obvious which class methods contain transactionmanagement logic andwhich don’t. The resulting confusion often takesmoretimeandeffortthanthedevelopmenttimesavedbyusinganAOPstrategy.

TheAutocommitstrategyisthemostconvenientforinitialdevelopment.It’spossible,oftenataJDBCdriverconfigurationlevel,tosetallconnectionstobe“autocommit” by default. Using this strategy, the JDBC driver automaticallyissuesa“commit”aftersuccessfulSQLstatementsanda“rollback”afterfailedtransactions.ThisstrategyhasthesameissueastheAOPstrategyinthatit’stoogranulartobeusefulwithmostJavaEEapplications.

Asyoumayhaveguessed,ItrendtowardusingtheServletFilterstrategyfortransaction management. It’s simple. It alleviates the need for developers toconcern themselves with transaction management issues. Should a given webtransaction require multiple units of work, this strategy allows that whereneeded.It’seasilyreusedinmultipleapplications.

You may notice that transaction state is actually retained in aTransactionContextclass.Thisallowsotherclassestomanagetransactionstateifneeded. For example, batch jobs and JMS queuemonitors require transactionmanagementthatcannotbeaddressedbyaServletFilter.

Note that the Servlet Filter and AOP transaction strategies can be easilycombined with other transaction management products such as Bitronix(http://docs.codehaus.org/display/BTM/Home), Atomikos(http://www.atomikos.com/), or JOTM (jotm.objectweb.org). Transactionmanagementproducts facilitatecommitand rollback strategies forapplicationsusingmultipledatasources;someapplicationshavesuchrequirements.

DATAACCESSOBJECTCODINGGUIDELINESAsmost use a JPA implementation such asHibernate for database persistencethesedays,let’sbeginwithaHibernateexamplesuchasListing10.2.

Listing10.2:HibernateDAOExample

Source:srcj2ee/architect/handbook/chap10/hibernate/CustomerHibernateDAO.java

Note that thisDAO extends the classBaseHibernateDAO that exposes thecurrentHibernatesession.Thisclassisavailableinthesourcedistribution.

DAOclassesdonotissuecommits,rollbacks,orsavepoints.TheconsistencymakesDAOclasseseasiertoreuseformultipleusecases.Icanimagineseveralusecasesthatrequireacustomerlookupbyid,andit’spossiblethatthelookupcan occur in the middle of a larger unit of work. Were the DAO to issue a

commitor rollback, itwouldeffectively interferewith the largerunitofwork.Furthermore, whichDAOs issue commits or rollbacks isn’t well documented.Theinconsistencywouldcostdevelopers timeas itwouldn’tbeobviouswherespecifictransactionsbeganandended.

DAO classes reference only entities, architectural components/utilities andotherDAOclasses.DAOclassesdonotreferenceclasses in thebusiness logiclayer, presentation layer, or deployment layer. This enforces separation ofconcernsandisinkeepingwithalayeredarchitecture.

Validate arguments forpublic andprotectedmethods.Thealternative is toallow the method to produce some type of derivative exception (such as aNullPointerException) that often takes more time to diagnose and fix.Furthermore,thevalidationisquickandrarelyimpactsperformancenoticeably.Note that theValidate utility from theApacheCommonsLang project is veryeffectiveforthispurpose.

AJDBCEXAMPLEIn the early days, we all learned native JDBC. In fact, knowledge of nativeJDBChelps developers diagnose errors typically coming out ofDAO classes.Thatsaid,thetimeswherenativeJDBCcodingisnecessarythesedaysarerare.It is more common to leverage JDBC helper utilities, such as those in theApache Commons DBUtils (http://commons.apache.org/dbutils/) project forconvenience. As an example, listing 10.3 presents a JDBC example thatleveragesDBUtilsforconvenience.

Listing10.3:JDBCDAOexample

Source:srcj2ee/architect/handbook/chap10/jdbc/CustomerJdbcDAO.java

Note that this DAO extends the class BaseJDBCDAO that exposes thecurrentJDBCConnectionaswellasfacilitatesDBUtilsusageforexecutingSQLstatements. Inaddition, thisexamplereliesonclassCustomerResultSetHandlerwhich is an implementation of ResultSetHandler interface for select results.

Theseclassesareavailableinthesourcedistribution.

JDBC objects created within amethod should be closed within the samemethod.ExamplesofthiskindofobjectincludePreparedStatement,Statement,ResultSet, CallableStatement objects. For many database platforms to avoidresource leaks, it’s necessary to close ResultSet, PreparedStatement,CallableStatement,andStatementobjectswhenyou’rethroughwiththem.SomeJDBCdrivers close theseobjects automaticallywhen theConnection is closedand some don’t. It’s easier to spot bugs involving resource leaks later if youadopttheconventionofclosingeverythingyoucreateatthislayer.NotethattheDBUtilslibraryprovidesutilitiestodothis.

UsehostvariablesinSQLstatementsinsteadofhard-codingliteralsinSQLstrings.DBUtilsadoptsthispractice.Asaconvenience,manydevelopersembedliteralsinSQLstatementsinstead.Listing10.4isanexampleofthebadpracticeofembeddingliterals.Noticethatthisexampleplacesacustomer IDdirectlyintheSQLstatement.Noticealsothat thisexampleuses the+operatorforstringconcatenation. Although using + is convenient, you can concatenate stringsfasterusingStringBufferandtheStringBuffer.append()method.

Listing10.4:BadlyWrittenUpdateStatementsqlText=“updateCustomer“+

“setLast_Name=‘”+customer.getLastName()“’,First_Name=‘”+customer.getFirstName()“’,Middle_Initial=‘”+customer.getMiddleInitial()“’whereCustomer_Id=“+

customer.getCustomerId();this.update(sqlText);The problem with the code in listing 10.4 is that it circumvents database

optimizations provided by Oracle, DB2/UDB, and many others. To get thebenefitofdatabase softwareoptimizations,youneed tousePreparedStatementobjects instead of Statement objects for SQL that will be executed multipletimes.Further,youneedtousehostvariablesinsteadofliteralsforliteralsthatwill change between executions. With listing 10.4, the SQL statement forCustomerID1willbedifferentthanforCustomerID2(“whereCustomer_Id=1” is different from “where Customer_Id = 2”). The original version of theupdatestatementinlisting10.3ismuchbetter.

Notice that because listing 10.3 uses host variables instead of literals, theSQLstatement is identicalnomatterwhat thequalifyinguser ID is.Further,aPreparedStatementisusedinsteadofaStatement.

To better understand the database optimizations possible when usingPreparedStatement objects, consider how Oracle processes SQL statements.WhenexecutingSQLstatements,Oraclegoesthroughthefollowingsteps:

1. Lookupthestatementinthesharedpooltoseeifithasalreadybeenparsedorinterpreted.Ifyes,godirectlytostep4.

2. Parse(orinterpret)thestatement.3. Figureouthowtogetthedesireddataandrecordtheinformationina

portionofmemorycalledthesharedpool.4. Getthedata.

When Oracle looks up an SQL statement to see if it has already beenexecuted (step 1), it attempts a character-by-character match of the SQLstatement.Iftheprogramfindsamatch,itcanusetheparseinformationalreadyinthesharedpoolanddoesnothavetodosteps2and3becauseithasdonethework already. If you hard-code literals in SQL statements, the probability offindingamatchisverylow(“whereCustomer_Id=1”isnotthesameas“whereCustomer_Id=2”).ThismeansthatOraclewillhavetoreparselisting10.4foreach portfolio selected. Had listing 10.4 used host variables and aPreparedStatement, the SQL statement (which would look something like“whereCustomer_Id=:1”inthesharedpool)wouldhavebeenparsedonceandonlyonce.

DB2/UDB uses different terminology but a similar algorithm for dynamicSQL statements. Use of the PreparedStatement over the Statement isrecommendedforDB2/UDBaswell.

Consolidate formation of SQL statement strings. As a former databaseadministrator, I spendasubstantialportionofmy timereading thecodeothershavewrittenandsuggestingwaystoimproveperformance.Asyoumightexpect,I am particularly interested in the SQL statements. I find it especially hard tofollowSQLstatementsconstructedbystringmanipulationscatteredoverseveralmethods. Itgreatlyenhancesreadability ifyouconsolidate the logic that formstheSQLstatement.

Listing 10.5a is a good illustration of this point. Note that the stringmanipulationtoformtheSQLstatementislocatedinoneplace.TheSQLstringisalsodefinedstaticallytoreducetheamountofstringconcatenation.

Listing10.5a:UsingaStringHostVariableforaDateFieldSelectsum(sale_price)

Frompurchase_orderWhereto_char(sale_dt,’YYYY-MM-DD’)>=?

Limituseofcolumnfunctions.Trytolimityouruseofcolumnfunctionstotheselect lists of select statements.Moreover, use only aggregate functions (e.g.,count, sum, and average) needed for select statements that use a “group by”clause. There are two reasons for this recommendation: performance andportability.

When you limit the use of a function to a select list (and keep it out of“where”clauses),youcanusethefunctionwithoutblockingtheuseofanindex.Inthesamewaythattheto_charfunctionprohibitedthedatabasefromusinganindex in listing 10.5a, column functions in “where” clauses very likely willprohibit the database from using an index. This results in slower queryperformance.RewritingtheSQLstatementasshowninlisting10.5ballowsmostdatabasestouseindices.

Listing10.5b:Querywithjava.sql.TimestampasaHostVariableSelectsum(sale_price)

Frompurchase_orderWheresale_dt>=?

In addition,many of the operations forwhich developers useSQL columnfunctions(datatypeconversion,valueformatting,etc.)arefasterinJavathanifthe database did them. I’ve had 5 to 20 percent performance improvement inmany applications by avoiding some column functions and implementing thelogicinJavainstead.Anotherwaytolookatit isthatyoucannottunecolumnfunctions because you cannot control the source code. By implementing thatlogicinJava,youcreatecodethatyoucantuneifnecessary.

Moreover, using non-ANSI standard column functions can also causeportability problems. Not all database vendors implement the same columnfunctions. For instance, one of my favorite Oracle column functions, decode,whichallowsyoutotranslateonesetofvaluesintoanother,isnotimplementedin many of the other major database platforms. In general, using columnfunctionslikedecodehasthepotentialtobecomeaportabilityissue.

Alwaysspecifyacolumnlistwithaninsertstatement.Manydevelopersuse

theshortcutofomittingthecolumnlistinaninsertstatementtoavoidhavingtotypeout a column list.Bydefault, the columnorder is the sameasphysicallydefined in the table. Listing 10.6a illustrates this shortcut, and listing 10.6billustratesthealternativeofexplicitlylistingdesiredcolumns.

Listing10.6a:InsertStatementwithoutColumnListInsertintocustomer

Values(‘Ashmore’,’Derek’,’3023N.Clark’,’Chicago’,’IL’,555555)

Listing10.6b:FullInsertStatementwithColumnListInsertintocustomer

(last_nm,first_nm,address,city,state,customer_nbr)Values(?,?,?,?,?,?)Explicitlylistingcolumnsininsertstatements,asillustratedinlisting10.6b,

isdoneforthesamereasonasexplicitlylistingcolumnsinselectstatements.Ifsomeone reorders the columns in any of the tables in the insert or adds newcolumns,theinsertcouldgenerateanexception,andyoumustmodifytheinsertstatement.Forexample, suppose thatdatabaseadministratoragainchanges theorder of the columns, putting column CUSTOMER_NBR first, and adds acolumncalledCOUNTRY. The developerwho used the shortcutwill have tochangecode.Thedeveloperwhoexplicitly listedallcolumnswillbeoblivioustothechangebecausethecodewillstillwork.Inaddition,notethatlisting10.6buseshostvariables,sothesamePreparedStatementcanbeusedforallinsertsiftherearemultipleinserts.

Asinselectstatements,explicitlylistingcolumnsinaninsertstatementisabest practice because it can eliminate the need for maintenance. Further,allowing reuse of the PreparedStatement improves performance, especially forinsertsoflargenumbersofrows.

Code test cases for all DAOmethods and put them in the test suite. Youshouldbeabletorunaregressiontestforallobjectsinthedataaccesslayeratanytime.Thisimprovesproductqualitybyautomatingareasonabletestprocess.

Define a standardmethod formanaging data needed forDAO test cases.DAOtestcasesaredependentonthedatausedtodevelopthetests.Shouldthatdatachange,testsmayfail,butnotbecauseofacodedefect.ThetestdataandDAOtestcasesneed tobekept insync.One toolset I’veusedwithsuccess toassist with managing this issue is the open source product DbUnit(www.dbunit.org). There are also other toolsets that can be used to solve this

issue.

XMLACCESSOBJECTCODINGGUIDELINESData access objects are classes that read and write persistent data. XMLmanipulation, because it’s really a data access operation, is part of the DAOlayer.AnXMLaccessobject (XAO) reads andwritesdata in anXML formatandconvertsthatformattovalueobjectsthatotherlayersintheapplicationcanuse.Asanexample,anXMLaccessobjectfoundintheAdmin4Jproductcanbefoundinlisting10.7.

Listing10.7:AnInterfaceforanXMLAccessObjectfromAdmin4J

publicinterfaceTaskTimerDAO{

publicSet<TaskTimer>findAll();publicvoidsaveAll(Set<TaskTimer>exceptionList);}Business objects useXAOs to interpret and produceXML data. Typically,

XAOsshouldhavelittle todowithimplementingthebusinessrulesassociatedwithprocessingthedata.XML-relatedcodeisseparatedtolimitandlocalizetheimpactthatchangesintheXMLstructurehaveonyourapplication.Ifthislogicwerescatteredinvariousplacesinthebusinesslogiclayer,forexample,itwouldbemuchhardertofindandchange.

Asanapplicationarchitect,youareresponsibleforformingcodingstandardsandguidelines.ThischapterprovidesimplementationguidanceandexamplesforstructuringXAOs.Inaddition,I’llshowyouawaytogeneratecodethatXAOscaneasilyuse,savingyoudevelopmentandmaintenancetime.

There are many XML products available to facilitate reading and creatingXML.However,theygenerallyfallintooneofthefollowingcategories:DOM-based,reflection-based,orcodegeneration-based.DOM-basedtechnologiesarebased directly on the Document Object Model (package org.w3c.dom) that’snowprovidedwiththeJDK.AsnativeDomcodeisverboseandawkward,usingacomplementarytechnology,suchasJDom(http://www.jdom.org/)ispreferabletousingaDOMparserdirectly.

Reflection-basedXML products use reflection to produceXML from Javaobjectsand transformXML into Java for reading.Anexampleofa reflection-basedXMLproductisincludedwiththeJDKinclassesjava.beans.XMLEncoderandjava.beans.XMLDecoder.

Another example of a reflection-based XML product is Castor XML

(www.castor.org).Code generation-basedXML products use a schema orDTD and generate

JavaclassesthatrepresenttheseXMLconstructsandalsotransformtheseJavaclasses intoXMLor transformXML into instancesof thesegeneratedclasses.The Apache XML Beans (http://xmlbeans.apache.org/) product is a goodexampleofthistypeoftechnology.

Avoiddirectuseof theDOMto interpretXMLdata. It is faster todevelopandeasier tomaintainapplicationsusingcomplementary technologies, suchasXMLBeansorJDOM,ratherthanusingaDOMparserdirectly.

Mypreference isXMLBeans,which generates Java source code that canread, interpret, and serialize XML documents conforming to a givenschema. The advantages of XMLBeans are that it maps XML documents toJavaclassesthatareeasyfordeveloperstouse,andthelearningcurveforXMLBeansisveryshort.

ApplyXMLtechnologiesconsistentlythroughouttheapplication.Whateveryour technology choices are, there is a tremendous benefit to consistency.Forinstance,ifthedevelopersofyourapplicationpreferJDOMandarecomfortablewiththatchoice,youhavelittlereasontouseXMLBeans.Consistencymakesthe application easier tomaintainbecause it reduces the skill sets required formaintenancedevelopers.ConsistencyalsoreducesthetimeittakestoinvestigatebugsbecausemaintenancedeveloperscanbeginwithabaseunderstandingastohowXAOsarestructured.

Place XML-related code into separate classes. One reason for separatingXML-relatedclassesfromthosethatimplementbusinessrulesistoinsulateyourapplication from changes in XML document structure. Another reason is thatseparatingXMLdocumentinterpretationandbusinesslogiccanleadtosimplercode. Further, ifmultiple applicationsmust read and interpret the sameXMLdocumentformats,keepingXML-relatedcodeseparatemakesiteasiertosharethatcodeacrossapplications.

ANXAOEXAMPLEAdmin4J uses the reflection-basedXMLEncoder andXMLDecoder that comewith theJDK.The implementationfor the interface in listing10.7 is inaclassnamedTaskTimerDAOXml,whichistoolargetoreprinthereinitsentirety.The

source is included in the download for Admin4J, which can be obtained atwww.admin4j.net.

Listing10.8isanexcerptfromTaskTimerDAOXmlthatillustrateshowXMLisreadandconvertedintoJavaclassesusingtheXMLDecoder.

Listing10.8:AnXMLDecoderExample

decoder=newXMLDecoder(newBufferedInputStream(newFileInputStream(xmlFileName)));

decoder.setExceptionListener(newDefaultExceptionListener(xmlFileName));

result=(Set<TaskTimer>)decoder.readObject();

Listing10.9:AnXMLEncoderExample

encoder=newXMLEncoder(newBufferedOutputStream(newFileOutputStream(tempFileName)));

encoder.setExceptionListener(newDefaultExceptionListener(xmlFileName));

encoder.setPersistenceDelegate(BasicTaskTimer.class,newDefaultPersistenceDelegate(newString[]{“label”,”dataMeasures”}));

encoder.setPersistenceDelegate(SummaryDataMeasure.class,newDefaultPersistenceDelegate(newString[]{“firstObservationTime”}));

encoder.writeObject(exceptionList);encoder.close();

FURTHERREADINGAlur,Deepak,JohnCrupi,andDanMalks.2001.CoreJ2EEPatterns:BestPracticesandDesignStrategies.NewYork:PrenticeHall.

Horstmann,CayS.,andGaryCornell.2008.CoreJava2,VolumeII:AdvancedFeatures,8thed.Essex,UK:PearsonHigherEducation.

Johnson,Rod.2002.ExpertOne-on-One:J2EEDesignandDevelopment.Indianapolis,IN:WroxPress.

CHAPTER11

BUILDINGBUSINESSOBJECTS

The business logic layer for Java EE applications combines data withapplication logic, business rules, constraints, and activities. I usually packagebusinessobjectsseparatelytomaximizethepossibilityofreuse.It’scommonforbusiness objects to use and coordinate the activities of multiple data accessobjects. Figure 11.1 illustrates how business objects function in a layeredarchitecture.

Figure11.1:UsingBusinessObjectswithinaLayeredArchitecture

Business objects are used by other business objects or classes in thepresentation or deployment layers, such as enterprise beans or web services.They often instantiate and use classes in the data access layer, such as thosediscussedintheprevioustwochapters.

BUSINESSOBJECTCODINGPATTERNSThefirstandsimplestcodingpatterncommonlyusedinthebusinesslogiclayer

is the Transaction Script pattern, as described by [Fowler]. This patternorganizes application code into a series of discreet transactions. For example,consider normal banking transactions youmight conduct at anATMmachine.Behindtheenteringofmypasscode,thereverywellmightbeatransactionscriptthatverifiesthatthepasscodeIenteredbelongstothecardIpresented.Behindmy cashwithdrawal, theremight be a transaction script to verifymy accountbalance, record the withdrawal transaction, and tell the ATM machine todispensethecash.Infact,everyactionIcantakeatanATMmachinecouldbedividedintoaseriesofdiscreettransactions.Beyondthisbankingexample,itispossible to look at all applications as a seriesof transactions that accept inputanddoapredeterminedsetofworkactivities.

TheTransactionScriptpatternisfrowneduponbymanyasbeingtoosimple.Havingseenmorearbitrarilycomplexcode (e.g., spaghetti code) than Iwouldlike, I see simplicity as a good attribute, not as a disadvantage. For simple tomoderately complex tasks, the Transaction Script pattern is completelyappropriate.Allbusinessapplications,regardlessofsize,havefeaturesthatfallintothesimpletomoderatelycomplexcategory.Infact,mostfeaturesformostbusinessapplicationsfallintothiscategory.

Becauseofitssimplicity,theTransactionScriptpatterniseasytoteach,evento very junior developers. Code following this pattern is usually easy tounderstand.

However, theTransactionScriptpattern isalsodislikedbymany,as it isn’ttruly object oriented. That is, it doesn’t comingle state with a set of relatedactions. Transaction script classes do not have state (e.g., fields). They acceptinputs, often in the formof entityorvalueobject form, and theyutilizeDAOlayer classes to performneeded reads orwrites.Object-oriented code tends tocombineapplicationdatawiththeactionsonitinthesameclassorsetofclasses.In this light, the Transaction Script pattern can be seen as a throwback toproceduralprogramming.

Classes implementing the transaction pattern serve as classificationcategories. For example, a collection of transaction scripts to manage bankaccounttransactionsmightbecalledAccountScriptsorAccountManager.Theseclasses do not have state. In fact,most oftenmethods on these classes can bedeclaredasstatic.

It is possible to reuse code using the Transaction Script pattern. In largebusinessapplications,sometransactionswillbecompositetransactions.Thatis,theywillmakeuseofotherexistingtransactions.ToreturntotheATMexample,

a script to “record a transaction”may very well be leveraged for a “deposit”transactionscriptaswellasa“withdrawal”transactionscript.

While complex tasks can be written as a large and complex series oftransaction scripts, these scriptsbecome fragile andmoredifficult tomaintain.Yes,youcanmitigate thissomewhatwithunit testingsupport.But thepunditswhofrownupontheTransactionScriptpatternarecorrectinpointingoutthatithas limitations. It is common for large business applications to have somefeaturesthatarereallytoocomplexfortheTransactionScriptpatternandneedamore object-oriented approach. The beauty of a layered architecture is thattransactionscriptcodeandobject-orientedcodecanco-exist.Thatis,feelfreetoutilize more advanced patterns for features that truly need it and transactionscripts for simpler features.There’snoobjective algorithm fordecidingwhichfeaturesaretoocomplexfortransactionscriptsandwhichneedmoreadvancedcodingpatterns.

BUSINESSOBJECTCODINGGUIDELINESNeverputanythingdeploymentspecificinanobjectinthebusinesslogiclayer.Businessobjects shouldbe reusable inanycontext (e.g.,web transaction,webservice, or batch job) without changes. This insulates business logic fromchanges and developments in the deployment or presentation layers, whichchangemorerapidlythananythingelse.

To keep business objects independent, business objects don’t referencepresentation tier classes or make any assumptions (save for transactionmanagement)about thecontext inwhich theywillbecalled.Theycanassumethat they are executed within the context of a transaction, as transactionmanagementtypicallyoccursatthepointofdeployment.

ManyJavaEEbooksguideyoutowardincorporatingbusinesslogicdirectlyintoenterprisebeans.Idon’tsubscribetothatviewbecauseoftherapidpaceatwhich deployment methodologies have changed over the years. Secondly,enterprisebeanusagehasdiminishedoverthepastfewyearsandisrecognizedasunneededcomplexityinmanycases.

All publicmethods should explicitly validate the arguments. If they don’t,you run a significant risk of generating a derivative exception, such as aNullPointerException,whichcan take longer todebugand fix. IfyougenerateanIllegalArgumentExceptionwith a clearmessage,programmingerrors in thedeployment layer or within business objects that call you will have a better

chanceatbeingcaughtinunittesting.

Alwayshaveaconsistentstrategyforinstantiatingbusinesslayeranddataaccess layer classes. Common strategies include autowiring with the help ofInversionofControl(IOC)softwareorbyusingtheFactorypattern.

TheFactorypatternconsistsofusingfactoryclassestoinstantiateclassesasillustratedinfigure11.2.

Figure11.2:UsingBusinessObjectwithinaLayeredArchitecture

The Factory pattern consolidates responsibility for instantiation andconfiguration,and italleviates thatconcernfromtherestof theapplication. Inthe simplest case, the Factory patternmerely instantiates a class, e.g., via thenewkeyword.Withmore complicated applications, itmayneed to interrogatetheapplication’sconfigurationtomakeadecisionastowhichconcreteclassisproduced.

IOC software products, such as Guice (http://code.google.com/p/google-guice/) or Spring (http://www.springsource.org/), provide you with ways toconfigureapplicationsbycontrollingwhichconcreteclass implementationsareused with a particular installation of the application. IOC software productsalleviate the amount of custom code needed to manage your applicationconfiguration. IOC software products also simplify some unit testing code astheyallowyoutoeasilystubclassesthataren’tcurrentlyundertest.Itispossible

tocombineIOCsoftwareproductusewiththeFactorypattern.TheuseofIOCproductsforcesrigoroususeof interfaces todecoupleclass

dependencies.Thishasadvantagesanddisadvantages.Thedecouplingdoestendto make classes more reusable; however, it also reduces the ability fordevelopment environments to provide call hierarchy information (i.e.,informationaboutwhichclassescallagivenmethodonaconcreteclass).Thisisinformation that is extremely useful to developers and shouldn’t be sacrificedlightly.

Many consider the use of IOC software products essential and use themconsistentlywith every project they undertake. I don’t subscribe to this view.IOCsoftwareproductsintroducecomplexitythatneedstohaveacorrespondingbenefit to offset that cost. Applications that have configuration options thatrequireusingdifferentimplementationclassesmightbenefitfromtheuseofIOCsoftware products. An example of this would be: applications that supportmultiple database platforms might require different DAO implementationclasses.Similarly,ifyoustubdataaccesslayerclassesorbusinesslayerclassesforunit testingpurposes,youmightbenefit from IOCsoftwareproductusage.Another thing to consider is that IOC configuration bugs are not alwaysstraightforwardtofindandfix.

Whicheverstrategyyouuse, it’s important touse itconsistently throughoutthe application. Having multiple methods for business or data access layerclasses causes confusion among developers and introduces unnecessarycomplexity.

Trendtowardstatelessclassesinthebusinesslayer.Thatis,trendtowarduseof theTransaction Script pattern. State (e.g., knowledge of the users’work inprogress beyond local variables needed for currently executing code) for webapplications ismore appropriately kept on the session in the formof entity orvalueobjectclasses.Keepingadditionalcopiesofstateinthebusinesslayerorother layers addsunneeded complexity in that keeping those additional copiesup-to-daterequiresadditionalcodeandviolatestheDRYprinciple.Instead,passinformationtothebusinesslayer,asneeded,toperformspecifictasks.

ABUSINESSLAYERCLASSEXAMPLEListing 11.1 contains a code excerpt from an example business layer class. Itmanagesdeletionofacustomer.Inthisexample:

Listing11.1:BusinessLayerClassExcerpt

Source:src/j2ee/architect/handbook/chap11/Customer.java

Notethatthisexamplefollowsalloftheguidelinesdescribedinthischapter.It doesn’t make any assumptions about its execution context. This method isstatelessandcouldbeexecutedfromawebtransaction,awebservice,abatchjob,oranyothercontext.

Thismethod validates its arguments and throws an unchecked exception ifthemethodargumentsaren’tvalidduetosomekindofprogrammingerror.Thismethodthengoesfurthertovalidatethatthiscustomercouldactuallybedeletedfromabusinessperspective.Inthisexample,thebusinessprocessingexception

isacheckedexceptionthatthecallermusthandle.Atthislevel,validationsthatneedtooccurregardlessofexecutioncontextareputhere.Ifthiswereusedinawebtransaction,theapplicationmightdisplaytheerrorstotheusersotheycouldbe addressed. If thiswere used in aweb service, these errorswould likely bepassedonintheresponsetothecaller.

This class delegates all data access class instantiation to a factory class(DAOFactory).ThisfactoryclasscoulduseIOCtechnologiesorsomeotherwayto instantiate the data access class requested.What’s used for configuring thedata access layer doesn’t affect this business layer method or impact how itoperatesinanyway.

ANADMIN4JBUSINESSLAYEREXAMPLEIn a previous chapter, a class diagram for the exception summary features ofAdmin4J was presented. This diagram is reprinted in figure 11.3. ClassExceptionTracker is the central business layer class providing these features.We’llfocusonthisclassasanotherexampleofbusinesslayercode.

Figure11.3:UsingBusinessObjectwithinaLayeredArchitecture

ThefirstexamplefromAdmin4Jisthebusinesslayermethodthattracksanexceptiongeneratedbyanapplication.Thismethodispresentedinlisting11.2.

Listing11.2:BusinessLayerClassExcerptfromAdmin4J

Notethatthisexamplefollowsalloftheguidelinesdescribedinthischapter.Thismethodvalidatesitsarguments.Thismethod,andinfacttheentireclass,isstateless. Furthermore, there is nothing deployment-specific about anything inthisclass.

This method is used by two classes: Log4JExceptionAppender andJdkLoggingExceptionHandler,which capture exceptions loggedviaLog4J andthe native JDK logging that’s part of Java itself respectively. Listing 11.3aillustrates usage of this business layer class within a Log4J appender. Thisexample does take great care to not throw an exception in order to avoidaccidentallycoveringuploggingofarootexception.Thiscareisnormalforlogappenders,butnotnormalformostpresentationlayercodeusingbusinesslogicclasses.Listing11.3bprovidesasimilarexampleforaJDKLoggingExceptionHandler.

Listing11.3a:ExampleUsageforBusinessLayerClassfromAdmin4JLog4JAppender

Listing11.3b:ExampleUsageforBusinessLayerClassfromAdmin4JJDKLoggingExceptionHandler

FURTHERREADINGAlur,Deepak,JohnCrupi,andDanMalks.2003.CoreJ2EEPatterns:BestPracticesandDesignStrategies,2nded.NewYork:PrenticeHall.

Fowler,Martin.2002.PatternsofEnterpriseApplicationArchitecture.Reading,MA:Addison-Wesley.

Gamma,Erich,RichardHelm,RalphJohnson,andJohnVlissides.1995.DesignPatterns.Reading,MA:Addison-Wesley.

CHAPTER12

BUILDINGTHEDEPLOYMENTANDPRESENTATIONLAYERSTHE

DEPLOYMENTANDPRESENTATIONLAYERSOFJAVAEEAPPLICATIONSAREUSEDDIRECTLYBYUSERS.

Objects in the presentation layer produce the pages or screens that usersphysicallyseeanduse.Thereareseveralaspectstothepresentationside:staticcontent, dynamic content, and navigation. For Java EE applications, HTMLpages typically provide static content; and a combination of JSPs and servletsusually provide dynamic content. For applications that require special effects(e.g.,mouse-overs),Javascriptcanbeused incombinationwitheitherstaticordynamically producedHTML.Users navigate pages using controls (e.g., pushbuttons)onthepage.

Objects in the deployment layer (which I call deployment wrappers)“publish”thecontentofthebusinesslogiclayertootherapplications.Examplesofdeploymentlayerconstructsincludewebservicesandenterprisebeans.Iwastemptedtocallthislayerthe“service”layer,butthatwouldleadtoconfusionasto why this layer contains enterprise beans. The deployment layer providesremotecallingcapabilityforotherapplications.Forinstance,itisnotuncommontosupportmobileapplicationsbypublishingRestfulwebservices;thoseserviceswouldbepartofthedeploymentlayer.

Deployment wrappers such as web services and enterprise beans arepurposely kept relatively simple and thin because they aremore difficult andtimeconsumingtodevelopandmaintainthannormalJavaclasses.Simple,thindeploymentwrappersarelesslikelytohavebugs.

Figure12.1depictstheroleofthepresentationanddeploymentlayers.

Figure12.1:ThePresentationandDeploymentLayerswithinaJavaEE

Application

WEBAPPLICATIONFRAMEWORKCONSIDERATIONSMostarchitects leverage third-party frameworks toassistdevelopment forwebservices and user interfaces. Without such frameworks, the amount andcomplexityofcodewithintheselayerswouldbeextremelyhigh.Consequently,the largest deliverable for application architectswith respect to these softwarelayersisdeterminingwhichframeworkswillbeused.

Someorganizationsmakeframeworkchoicesfortheselayersatanenterpriselevel.Therearegoodreasonsfordoingthis.Mostframeworkshavesignificantlearning curves. Leveraging the same framework set across the organizationoptimizes the time spent learning these frameworks. It alsomakes transferringdevelopers between applications easier and less costly. Furthermore, byconsolidating the frameworks inuse, it becomes easier to share commoncodeacrossapplicationsandgetgreaterreuse.

Some organizations leave framework choice up to individual applicationteams.Inthesetypesoforganizations,applicationarchitectseitherdecidewhichframeworkswillbeusedortheyfacilitatethedecision.Examplesofpresentationframeworkscommonlyused includeSpringMVC,ApacheStruts (orStruts2),JavaServerFaces,GoogleWebToolkit,Freemarker,ApacheVelocity,andmanyothers. Examples of web service frameworks commonly used includeApacheAxis(2),ApacheCXF,GlassfishMetro,andmanyothers.

Once framework decisions aremade, application architects usually provide

usage guidance. This guidance should address cross-cutting concerns such aserror handling, transaction logging, configuration, and build/deploymentmethodologies. Furthermore, I typically will provide a couple of workingexamples.

Thereareseveralconsiderationscommontothedeploymentandpresentationlayers. One of the most important considerations is effectively reusingpresentation code. Every website has graphics that are consistently reusedthroughoutthesite.Havinganabilitytoreusevisual“components”cangreatlyoptimizedevelopmenttime.Thewebframeworkchoicefortheapplicationwilllargelydictatestrategiesforcreatingvisualcomponentsandeffectivelyreusingcodeinthepresentationlayer.Somewebframeworksprovidebettersupportforcreating and reusing visual components than others. The choice of webframework makes such an excellent example for illustrating a process forselectinga technicalproduct that Iuse it asanexample in thechapterentitled“Making Technology Product Selections.” Material on how to code usingspecificwebframeworks,suchasSpring-MVC,JavaServerFaces,orStruts,isoutofscopeforthisbook.

SECURITYCONSIDERATIONSAnother important consideration is security.Most organizationswill provide asecurity architecture for the enterprise alongwith processes for defining usersand authorizing those users for specific web applications and assigning themsecurityrolesandsecuritygroups.Mostdeveloperscanassumethatusershavealreadybeenauthenticatedandareauthorizedtousetheapplicationbeingcalled.DeveloperscanassumethattheJavaEEcontainerwillprovidethemtheidentityoftheauthenticateduserandthesecurityrolestowhichthey’vebeenassigned.

The Java EE containerwill enforce security constraints definedwithin theweb.xmlconfigurationfileforyourapplication.SecurityconstraintswillspecifysecuredURLsandindicatewhichrolesareallowedaccesstothem.Forinstance,ifallURLsinyourapplicationrequiretheassignmentoftheManagerrole,youmight add a security constraint like the following to the web.xml file of theapplication:<security-constraint><display-name>RestricttothosewithManagerauthority.</display-name><web-resource-collection>

<web-resource-name>ProtectedArea</web-resource-name><url-pattern>*.jsp</url-pattern><url-pattern>*.html</url-pattern></web-resource-collection>

auth-constraint><role-name>Manager</role-name></auth-constraint>

</security-constraint>

If your application has URLs that are publicly available, it’s common tomake all securedURLs have a common pattern so they can be specified in asecurityconstraint(e.g.,secure*).Manyapplications,however,haveadditionalsecurityrequirementsbeyondmerelyprotectingspecificURLpatterns.

While the Java EE container will provide the credential or user id for thelogged in user from the HttpServletRequest, it’s common for applications torequire additional information about the user (e.g., full name, e-mail address,etc.). For example, some applications display the name of the logged in user.Someapplicationshaveneedtoinitiatee-mailwheretheuser’sfullnameande-mail addressareused.Additionally,other layersbesides thepresentation layermay need this information. For example, business logic that needs to keep anaudittrailofauser’sactionswillalsoneedtheuseridfortheloggedinuser.

As knowledge about the current logged in user is required in mostapplications, I usually incorporate a User context into the applicationarchitecture and populate it using a servlet filter. This idea is similar to theTransaction Management filter introduced in chapter 10 that maintained aTransactionContext. Classes in the presentation layer that needed informationabout the logged inuserwould leverage theuser context.For example:StringuserId=UserContext.getCurrent().getUser().getUserId();Anexampleofafilterthatmaintains theusercontextfor theapplicationcanbefoundin listing12.1.Notethatneededuserinformationiscontainedwithinavalueobjectcreatedforthatpurpose.

Listing12.1:SampleUserContextManagementFilterLogic

Source:srcj2ee/architect/handbook/chap12/UserContextManagementFilter.java

If your application has logic that presents different options for users withdifferentsecurityroles,thenasapracticalmatteryouneedtobeabletoemulatedifferent users for testing purposes. As an example, additional menu optionsmightappearformanagersthataren’tavailableforstaff.Wecanextendtheusercontextparadigmtohandleemulatingotherusersaswell.Listing12.2providesan example of how the user context concept could be extended to allow useremulation. For testing purposes, merely set the emulated user value object tovaluesyouwanttotestwith.

Listing12.2:SampleUserEmulationLogicpublicclassUserContext{

publicUserVOgetUser(){if(this.emulatedUser!=null){returnthis.emulatedUser;

}

returnthis.currentUser;

}

publicvoidsetEmulatedUser(UserVOemulatedUser){this.emulatedUser=emulatedUser;

}

}

Source:srcj2ee/architect/handbook/common/user/UserContext.java

ERROR-HANDLINGCONSIDERATIONSOnetopicthatalwayscomesupinpresentationlayercodingiserrorhandlingforexceptions that a user could correct. For example, many sites allow you toregisterasauser.Mostof thesesiteshaverequirementsfor theusernameyouselect.Forexample,manywillrequireatleasteightcharacters.Iftheuserweretoenterausernamethat’stooshort,theusercouldeasilycorrecttheirinputandresubmittheirregistration.Incorrectableerrorslikethis,wedon’twanttothrowa runtime exception. Instead,we’llwant to display amessage telling the userwhatfieldisincorrectandwhatthecorrectanswerrequirementsare.

Most web frameworks have a strategy for handling correctable errors anduser messages. However, generic strategies for user messages tend to not beaestheticallypleasing.Furthermore,it’slikelythatthebusinesslogiclayerwouldidentify the correctable errors. Tomake the business logic layer aware of thespecificwebframeworkinuse,sothattheframeworkstrategycouldbeused,isundesirablebecauseitviolatestheseparationofconcernsprinciple.Thebusinesslogiclayershouldnotbeawareofitsexecutioncontext.Onestrategyistocreateacustomcheckedexception(e.g.,CorrectionsRequiredException) thatcontainsinformationabouttheerrorandanappropriatemessage.Thepresentationlayerwouldbeforcedtocatchtheexceptionandproperlyformattheerrormessageforthe user. This is a little more work, but it does allow flexibility for handlingcorrectableerrors.

SUPPORTINGMOBILEDEVICESAsmobiledevicesupportisarequirementforlargerJavaEEapplicationsthesedays, it deserves focus.Mobiledevices canbe supported in largely twoways:through the mobile browser as a website specifically designed to display onsmallerscreens;andasacollectionofservicesthatsupportnativemobiledeviceapplications.ProvidingaJavaEEsitecateringtosmallerscreensisusuallytheeasiest,asitonlyaffectsthepresentationlayer.Forsimplesites,itispossibleforthesamemarkuptobeusedforlargeandsmalldisplaysizesbyusingdifferentCSS style sheets for different types of displays. For those that aren’t familiar,thiscanbeaccomplishedusingthemediaattribute.Acoupleofsimpleexamplesfollow: <link rel=”stylesheet” type=”text/css” href=”stylesheet.css”media=”screen” /> <link rel=”stylesheet” type=”text/css” href=”stylesheet-small.css”media=”handheld”/>Themediaattributealsosupportsattributesforassigningstylesheetsbasedondisplayheightandwidthandavarietyofmorespecificcharacteristicsthanscreenandhandheld.

Asapracticalmatter,thistechniqueonlyworksonsimplesites.Forcomplexsites with a large number of controls, it is common to slim down the site(provide lesscontentand fewer features) fordeviceswithsmaller screens.Forthesesites,therewillbetwoormoresetsofmarkup.Thedeviceisredirectedtothe markup that will best display on the size of the screen it has. There areseveralways to accomplish this redirection.The simplest I’ve seen is throughJavascript.<scripttype=”text/javascript”><!--

if(screen.width<=700){window.location=“http://mobile.mysite.com”;}

//--></script>

Another alternative is to provide web services that allow a native mobiledeviceapplicationtoobtaindataandposttransactions.Thisoptioncanbeusedtoprovideamorerobustend-userexperience,butitrequiresmoreworkandismore expensive. Providing a Java EE site that supports native mobileapplications will largely affect the deployment layer.Most mobile developersconsiderRestfulwebserviceseasiertoconsumethanSOAP.Furthermore,mostmobiledevelopersconsiderJSONformatdataeasiertousethanXML.

There are several products that support reading and formatting JSONdata.Thisproductselectionshouldbetreatedjust likeanyotherproductselection;Iprovideguidanceonmaking technologyproduct decisions in thenext chapter.

Two popular open source products in this space are Jackson(http://jackson.codehaus.org/) and GSON (https://code.google.com/p/google-gson/ ).Likewise, therearemultipleproducts thatprovideRestfulwebservicesupport. Two popular open source products in this space are Apache CXF(http://cxf.apache.org/)andRestlet(http://restlet.org/).

It is not uncommon for native applications to requireusers to authenticate.How the mobile application manages authenticating the user depends on thesecurityproductchosen.Itisnotunusualforthemobileapplicationtomaintaincookies with security tokens that the server can interrogate or providecredentials. Regardless, all communication with mobile devices should beencrypted(https)attheveryleast.

CODINGGUIDELINESKeepeverywebservice,EJB,orpresentationlayerclassthin.Testingtheseclasses requiresacontainer.Whileenvironments inwhich to test theseclassesare generally available and unit tests can be written against these classes,deploying changes to these classes is generally more time consuming. If youwant tooptimizedevelopment time,delegatingworkperformedat this level toclassesthatarelocallydebugableanddon’trequirecontainerservicesisadvised.

Keep HTML markup (e.g., JSP page) embedded logic thin. While taglibraries, EL expressions, and other features make it possible to embedcomplicated logic in HTML markup, writing unit tests for these pages thatensuretheybehavecorrectlyforusersisdifficultandtimeconsuming.Anythinginmarkupthatincreasesthenumberoftestcasesincreasesongoingmaintenancecostsmuchmore than adding those test cases in classeswhere comprehensiveunit tests are easier to write and maintain. Of course, some of this will beunavoidable for many applications. In places where you have the option ofdelegatingcomplicatedlogictomoreeasilytestedclasses,doit.

COMMONMISTAKESPutting business logic in presentation layer or deployment layer classes.Business logic tends tomake JSPs and servletsmore complex anddifficult tomaintain. Furthermore, this logic isn’t easily reusable in other contexts.Consequently, business logic incorporated in this layer has a higher chance ofbeingcopiedandviolatingtheDon’tRepeatYourself(DRY)principle.

Nottakingadvantageoftemplatingtechnologies.Mostpresentationproductshave templating features that make it easier to reuse HTML markup andviolatingDRY.Thiswillkeep thepresentation lessverboseandofteneasier tomaintain.Forexample,Ican’timagineimplementingaJSFapplicationwithoutusingFacelets’ templating features (whichwere formally incorporated into theJSF specification in version 2.0). Struts, another popular presentation product,also provides templating features. Not utilizing templating technology oftenleadstolargerepeatedsectionsofHTMLmarkup.

CHAPTER13

MAKINGTECHNOLOGYPRODUCTSELECTIONS

It is common for architects to guide the selection process for technologyproducts. Sometimes the products selected are directly utilized by end-users.Sometimes the products selected are libraries incorporated into applications tosave development time and support resources. My experience is that mostorganizations don’t approach technology selection in a very structured ororganized way. In this chapter, I present strategies for making technologyproductdecisions.Asthechoiceofwhichofthemanywebframeworkstouseisacommontechnologyproductchoice,Iuseitasanexample.

The choice of a web framework is one of the most important productselections made for Java EE applications. Framework choice is not an easydecision, and the potential effect of these choices on development andmaintenancecostsislarge.Giventheimportanceofthesedecisionsandproductchoices in general, let’s spend some timedetailing strategies formaking thesetypesofdecisions.

PRODUCTDECISIONCRITERIAWith regard to web service or web presentation frameworks, there are manyproductchoicesavailable.Weneedaway to rate theseproductsandhopefullydifferentiate them to the point where a logical choice will develop. The“attributes” on which we rate these frameworks in essence become decisioncriteria.

Commondecisioncriteriathatnormallymakethelistinonewayoranotherareasfollows:

FitnessforObjectiveEaseofUse

MarketShareSwitchingCostsExpectedCostSavings(overacustomsolution)LevelofCommunityActivityPerformanceDependencyRequirementsLicensing

Notallof thesecriteriaareequallyweighted;somemaybemoreimportantthanothers.Iusuallyweighteachofthesecriteriawithahigh,medium,orlow.Furthermore, I usually rank each product choicewith respect to these criteriafrom1to10,with10beingthebestrating.

Fitness for Objective. Is the product choice designed to be used for yourintended purpose? Are others using it for a similar purpose? This criterionsupports the principle “Swimwith the stream.”By using products as they aredesigned,you increase the likelihood that the resultingapplicationwillbenefitfrom future product improvements. For example, relational database productsare optimized for third-normal form. In the early days of relational databases,performance of joins was a frequent issue. However, over time, databaseproducts have solved these performance issues as relational database theoryincents normalized designs. Userswho used normalized designs benefited themostfromtheseimprovements.

These typesof criteria aremostoftenphrasedas a list of specific features.Forexample,whenchoosingaContentManagementSystem,thelistoffeaturesmeasuring “fitness for objective” might include spell checking, audit/changehistory,WYSIWYGeditingcapabilities,etc.Thisfeaturelistisdesignedtohelpyoudetermineiftheproductchoiceisconsistentwithhowyouwishtousetheproduct.

Drawinganexampleusingawebpresentationframework, let’ssupposethebusinessobjectiveistodelegatepresentationdesigntoHTML-literatespecialists(which typically cost less and are more plentiful). With that objective, anypresentationproductthatleveragedHTMLskillsetswouldbeadvantageous.Achoice ofApache’sWicket (http://wicket.apache.org/),which relies heavily onJava coding skill sets, would not fit the business objectives as well asframeworksthatwereHTML-based.

You also have the best chance of capitalizing on the experience of others.Frequently, problems—andhopefully their solutions—are reported in blogs onthe Internet. The chance that a problem you encounter has been previouslyreportedandsolvedincreasesifyouruseisconsistentwithhowtheproductwasdesignedtobeused.

EaseofUse. Choosing products that are easy to use optimizes training costs,lowers development and support time, and potentially reduces the mean timefromdefectreportingtofix.Easeofusealsomakestheproductmoreaccessibleto a wide variety of developers and provides management with greaterflexibility.

Let’sconsiderexamplesatbothendsofthespectrum.Toadevelopmentteamthat receivesdetailedHTMLpagedesigns for theapplications theybuild,webpresentation frameworks that rely on HTML templating, such as JSP,Freemarker,VelocityandJavaServerFaces,willbeeasier touse thanWicket,whichconsistsofJavacodeexclusively.

MarketShare.Choosingproductsthataremorewidelyusedmakesiteasiertoacquiredeveloperswithpreviousexperiencewiththatproduct.Italsoincreasesthe chances that solutions will be posted on the Internet for problemsencountered indevelopment.Also,productswith lowmarketsharesareat riskforbeingabandonedand,consequently,willnolongerbeenhanced.Yes,iftheproduct is open source, you can enhance it internally, but rarely willorganizations fund projects like that. In that case, it’s usually better to switchproducts.

Market sharenumbersareusuallyhard tocomeby. I’ve found twoproxiesfor market share: search engine keyword search data and job posting data.Search engine keyword search data can be obtained from Google Trends(http://www.google.com/trends/explore).A good source for job posting data isavailableatwww.indeed.comtrendingpage(http://www.indeed.com/jobtrends).As an example, let’s look at the popularity of several web presentationframeworksaspresentedinfigure13.1.

Asyoumight expect,ApacheStruts is themarket leader followedby JavaServerFaces(JSF)andSpringMVC.Note that jobpostingdata,whichIcan’tpresentduetolicensingrestrictions,showSpringMVCinsecondplacewithJSFin third.There are sometimesdifferencesbetween trendsnotedby jobpostingdata and keyword search data; you’ll have to make a judgment as to whichresults more closely represent market share. All other web presentation

frameworks included inmysearchhadsmallmarket sharescompared to thosethree.

Figure13.1:SearchEngineKeywordTrendDataforWebPresentationFrameworks

Source:GoogleTrendstakenonNovember17,2013.

Mypurposeisn’ttoadvertiseforStruts,SpringMVC,orJSF.Mypurposeisto illustratehoweasilyyoucangetanestimateofmarketshareofaparticularframeworkor product; and that information should be a factor in the decisionbeingmade. If you use awebpresentation framework not listed here, I inviteyoutodoyourowncomparisons,includingthatframework.

Asanotherexample,I’verunasimilarcomparisonforseveralwebservicesframeworkscommonlyusedwithJavaEEapplications.Ipresentitinfigure13.2.

Figure13.2:SearchEngineKeywordTrendDataforWebServicesFrameworks

Itissurprising,butApacheAxisisstillthemarketleader,despitethefactthatthe product was rewritten and released as Axis2. The Axis product was lastreleased in 2006, and all development effort has shifted to Axis2. AnotherApacheproduct,CXF, appears in secondplace, butmay in fact be themarketleader relatively soon. This information should be a factor in making a webserviceframeworkdecision.

Switching Costs. No matter what your product choice is today, it’s alwayspossiblethatyourrequirementswillchangeorthattheproductyouchosewillbedepreciatedinthefutureorbecomeobsolete.Inthatcase,anyapplicationsusingthat product will need to be changed to use a competing product instead.Because of this, products that can more easily be switched out to use acompetitorshouldreceiveahigherratingthanthosethatcan’t.

There’s no objective measurement for switching costs. I usually assign ahigh,medium,or lowratingbasedonabriefsurveyofproductdocumentationexamples. In the case of web services frameworks and web presentationframeworks, switching costs for all products are high and cause products toreceivealowrating.Becausethisfactordoesn’tdifferentiateanyoftheproducts,it’s not important when discussing web presentation or web servicesframeworks.Imentionitbecauseitdoesdifferentiateothertypesofproductsandshouldbeconsidered.

ExpectedCostSavings(overacustomsolution).Acustomsolutionisalwaysanoption,butnotalwaysanattractiveone.Inordertoestimateexpectedsavingsof choosing one product or another, you need a comparison base. That is,choosing product 1 over product 2 will save us 200 hours of work. But, to

providesuchanestimate,youneed tohaveaproduct tocompare to. Iusuallychooseacustom/homegrownsolutionasthatcomparisonproduct.

Havingsaidthat,thecustomsolution—let’ssayforpublishingawebservice—doesn’tmeanreplicatingallfunctionalityintheApacheAxis2product,perse.Itmeansproducingapublishingmethodjustgoodenoughtopublishonlywhat’sneededforyourproject.

Ifyouchoosethesamecomparisonbaseproduct(e.g.,acustomsolution)forall products in consideration, then expected savings becomes comparable.Theproductwiththemostsavingswillberatedthehighest,andtheproductwiththeleastsavingsratedtheleast.

Asanexample,atarecentclient,weneededto implementasinglesign-on(SSO)product.Duringthecourseoftheevaluation,weestimatedthatitwouldtakeapproximately1200hoursofdevelopmenttocustombuildanSSOsolution.We did similar estimates of implementation costs for each of the open sourceproduct candidates.We eventually chose JOSSO (www.josso.org),withwhichwe could make slight customizations and implement it enterprise-wide for acombinedcostofapproximately200hours.

LevelofCommunityActivity.Ifsomeofyourproductchoicesareopensourceprojects,it’slessriskytochooseprojectsthatareactivelymaintainedthanthoseprojectsthatarenot.Thechanceofaproductbecomingobsoleteismuchgreaterforprojects thataren’tmaintained.Furthermore,youhave littlehope thatbugsencounteredwiththeproductwilleverbefixedorthattheproductfeatureswillbeenhanced.

One of the easiest ways to measure community activity is to average thenumberofreleasesperyearforthepastthreeyears.Thisinformationisavailablefor most open source projects. Another way is to measure the mean timebetweenreleasesforthepastthreeyears.Mychoiceofthreeyearsisanarbitrarychoice.What’simportantisthatyoumeasureeachproductidentically.

If you’re concerned that one project might be skewing the statistics byreleasingmorequicklywithfewerfeatures,youcanalwaysmeasurethenumberof defects and improvements in those releases for the same time period.However, gathering this information, while available, takes more effort.Furthermore,itmissesthepoint.

What’simportantistodetectprojectsthathaveverylittleornoactivityandratethemlower.Asanexample,theApacheAxis2webservicesproducthashadninereleasesinthepastthreeyears.TheApacheCXFwebservicesproducthas

hadthirteenreleasesinthepastthreeyears.Fromthesestatistics,it’sclearthatbothprojectsareveryactivelymaintained.Iwouldratethemequalwithregardto community activity, despite the slight number difference in the number ofreleases.

Performance. Yes, performance is a consideration. However, you might notneedtogototheexpenseofconstructingandrunningperformancecomparisonsfortheseproductsyourself.Oftenformainstreamframeworksandproducts,youcanfindpublishedperformancecomparisons.Evenifthosecomparisonsareonoldversionsof theproduct, the time and expenseof constructing and runningyour own performance benchmarks often isn’t worth the effort if publishedaccountsareavailable.

For example, surveying the Internet for performance benchmarks of webservicesAxis2andCXF,Ifoundfourseparateaccountsthatjudgedperformanceof both products favorable, with minor differences noted for different databindingstrategies.Idon’tindicatethosesourcesasthistextwillbedatedbythetimeyoureadit;youcandoyourownresearch.Mypointisthatit’spossibletogather information about performance comparisons between products withoutgoingtotheexpenseofconstructingarigoroussetoftestsyourself.

DependencyRequirements.The fewer the dependency requirements, the lesschance of library version conflicts. A library version conflict is when oneproductrequiresversionxofalibrarywhileanotherproductrequiresversiony.Asanexample,sayoneproductrequiresApacheCommonsLoggingV1.0whileanotherrequiresV1.1.AsthereareAPIdifferencesbetweenthetwo,oneofthetwoproductsusingithasachanceofrunningintoa“methodnotfound”erroratruntime.

An open source product called JarAnalyzer(http://www.kirkk.com/main/Main/JarAnalyzer)will letyouknowaboutjarfiledependencies. However, its analysis doesn’t go far enough to tell you aboutmethod signature issues that can cause runtime linkage issues like what Idescribedabove.

Withrespecttowebserviceandwebpresentationframeworks,mostchoiceshave large numbers of dependencies. The only exception I know of is theFreemarker (http://freemarker.sourceforge.net/) template engine, which is usedby some to produce dynamic HTML instead of JSPs. Having said that,Freemarkerhasotherlimitationsasawebpresentationframeworkandmightnotbeyourbestchoicewhensomeof theotherdecisioncriteriaareconsideredas

well.

Licensing.Manyorganizationshaveguidelinesoverwhattypesofopensourcelicensesareacceptable.Thisisparticularlytrueforsoftwarethatwillbesoldasaproductassomeopensourcelicenseshaverestrictions.Mostorganizationswillhavea standard listofopen source licenses theywill accept andaprocess forevaluatingnewlicensesasneeded.

MAKINGAPRODUCTDECISIONWhen doing research for a particular product, it usually involves multiplepeople. Typically, it’s the application architect that facilitates these kinds ofdecisions.Inthefirstmeeting,Iusuallysuggestasetoffeatures/decisioncriteria(patternedafter the conceptsdescribedabove) andgetgeneral consensus as towhat criteria these products will be judged on. It’s possible that additionalcriteriamightbeproposedanddiscussedafterthismeeting,andthat’sokay.

Additionally, I suggest a list of products that shouldbe considered andgetgeneral consensus for that list.At this stage, if a product remotely appears tohaveachanceatfulfillingthebusinessrequirementsforyourproject, itshouldbe added to the list. Bad suggestions will get eliminated down the line asdifferentfeaturesareidentifiedandmeasured.Youalsodon’twanttoappeartobegamingtheselectionprocessbyunilaterallyeliminatingsomebody’sproductsuggestionupfront.

Thenexttopicofdiscussionistheweightthatshouldbegiveneachcriterion.AsIstatedintheprevioussection,somecriteriaarelessimportantthanothers.For example, fitness of purpose is much more important than dependencyrequirementsformostproductdecisions.

Many developers will over-rate the importance of performance in makingframeworkdecisions.Slightdifferences inperformancearen’tmaterial tomostorganizations. Just because oneweb service frameworkhas a slight edgeoveranother in a given test, doesn’t mean that you should necessarily choose thehighestperformingproduct;othercriterianeedtobeconsidered.

Asanexample,IparticipatedinaprocesstoevaluateContentManagementSystem (CMS) products for use with one of my client’s public sites. Thisselectionwasconducted in thesummerof2010.The readershouldnote thataCMSproductwasalreadyinusebythisclientbuthadsignificantlimitations.Inthe first meeting of the people conducting this research, we decided upon aninitiallistofproductstoevaluate,alistoffeaturesandcharacteristicsthatwould

be examined and evaluated, andweights thatwould be assigned to individualfeaturesandcharacteristics.ThatlistdidincludetheCMSproductcurrentlyusedsincestatusquoisalwaysanoption.

Theproject scopewas limited bymanagement to open source products, asthere was no funding for proprietary software purchases. Furthermore,managementestablished the task forcepersonneland time frame limits for theevaluation.With those guidelines inmind, the list of products included in theevaluationwasdeterminedbygroupconsensustobeasintable13.1:

Table13.1:ProductsIncludedinaCMSProductDecision

Product Version

OpenCms 7.5

Drupal 6.17

Joomla 1.5.318

WordPress 2.9.2

Alfresco3.3

DotNetNuke 5.4.2

Typo3 4.3

The versions of the products evaluatedwere the current stable releases forthoseproductsat the timeof thestartof theevaluation.Therearemanymoreproducts that could have been considered, but including every product in theCMSspacewouldhavebeentoolaborintensive,giventhenumberofpeopleonthe task force and the time limit imposed. Therefore, this narrowed-down listwasdeterminedbyaconsensusofmembersinthattaskforce.

Additionally,alistofproductfeaturesandcharacteristicsweredetermined,aswell as an initialweight thatwould be assigned to those features. This list offeaturesandweightsarelistedintable13.2.Inaddition,I’velistedthetypeofdecisioncriteriasupportedbyeachindividualfeaturelisting.

Table13.2:FeaturesEvaluatedinaCMSProductDecision

DecisionCriteriaType Feature(1–10)Priority

(High/Medium/Low)

DependencyRequirements

SingleSign-onCompatability High

DependencyRequirements

SupportedDatabases Medium

DependencyRequirements

SupportedPlatforms Medium

EaseofUse ContentOrganizationSupport High

EaseofUse FriendlyURLSupport Low

EaseofUse ImageResizingSupport Low

EaseofUse MacroLanguage Medium

EaseofUse MenuSupport High

EaseofUse SiteMapSupport Medium

EaseofUse Spell/GrammarChecking Medium

EaseofUse TemplatingSupport High

EaseofUse WysiwygEditingSupport High

FitnessforObjective AdvertisingManagement Low

FitnessforObjective ContentApproval High

FitnessforObjective ContentScheduling Low

FitnessforObjective Dead-linkDetection Low

FitnessforObjective Import/ExportSupport High

FitnessforObjective InternationalCharacterSupport Medium

FitnessforObjective OnlineAdministration High

FitnessforObjective RSSSupport High

FitnessforObjective SearchSupport High

FitnessforObjective VersionControl High

FitnessforObjective WorkflowSupport Medium

LevelofCommunityActivity

NumberofReleasesSinceJan.1,2008 Medium

MarketShare MarketShare(percentJobPostingsasproxy) Medium

OwnershipImpact CommercialTrainingOptions Medium

OwnershipImpact CustomAdd-on/Plug-inSupport High

OwnershipImpact Documentation Medium

OwnershipImpact UsageLicense Medium

OwnershipImpact VendorSupportAvailability High

OwnershipImpact WindowsSupport High

Performance Multi-UserConcurrentEditingSupport High

Performance Support3xtheCurrentNumberofPages High

Performance SupporttheCurrentPublicSiteTransactionVolume(pages/sec)

High

Security AuditTrail Medium

SwitchingCosts DynamicContent High

SwitchingCosts StaticContent Medium

Thenexttopicofdiscussionforthatinitialmeetingisdividingtheworkforevaluating products with respect to the criteria that’s been chosen. Usually, Isuggestratingeachproductforeachcriterionusingaratingof10to1,with10beingthebestratingand1beingtheworst.Astodividingthework,thereareacoupleofstrategies,eachwithadvantagesanddisadvantages.

The first strategy is to assign each person to completely rank one ormoreproducts with respect for each of the criteria. Considering a web servicesexample,haveonepersonratetheApacheAxis2productforalldecisioncriteriadecidedupon.Thishas theadvantageofminimizing the learningcurvefor theteam member and highly leveraging the learning they experience. It has thedisadvantagethatratingstandarddifferenceswilloccurbetweenproducts.Thatis, the person who rated switching costs for Axis2 will be different than thepersonwhoratedCXF.Theratingsfortheseproductsmightdifferbecausetheyhavedifferentevaluators;notbecauseofproductdifferences.

Anotherstrategyis toassignalldecisioncriteriatotheteam(allmembers).Their responsibility is to evaluate all products against each criterion. Thisincreases the likelihood thatdifferentproductsare rated inaconsistentway. Italso guarantees that any one reviewer can’t materially bias the group for oragainst a particular product due to private concerns. The disadvantage here isthat each teammember has to learn about each product,which costsmore intermsof time spent.However, I personallyprefer this approach.Usually,withthesetypesofdecisions,theyareimportantenoughthatit’sworththeadditionaltimespent.Italsoprovidestheopportunitytoquestionanotherteammember’sratingsifthereisdisagreement.

Once product decisions for presentation and deployment wrappers such as

webservicesaremade, theproductsneed tobe integrated intoyourproject(s),andusageandcodingguidelinesestablishedfortheiruse.

CHAPTER14

BUILDINGARCHITECTURALCOMPONENTS

Architecturalcomponentsareclassesandstaticutilitiesgenericenough tobeused formanyapplications.Afteryou’ve identifiedaneed for an architecturalcomponent, your first step should usually be looking in themarketplace for acomponentthatmeetsthatneed.Irecommendstartingyourmarketplacesearchby checking out open source alternatives. If you have the necessary budget,commercialalternativesshouldbeincluded.Opensourcealternatives,whichcanbejustasgoodascommercialsoftware,areusuallymucheasiertoacquireandalot easier on the budget. At the end of the chapter, I highlight some of myfavoriteopensourcewebsites.

Opensourceprojectsthatroutinelyappearinmyprojectsarethefollowing:

ApacheCommons(http://commons.apache.org)Lang—GeneralJavalanguageutilitiesIO—CommonUtilitiesforclassesinjava.ioBeanUtils—UtilitiesformanipulatingJavabeanandPOJOclassesCollections—UtilitiesformanipulatingCollectionclassessuchasMapsandSetsDbUtils—UtilitiesforsimplifyingJDBCcodeApacheLog4J(http://logging.apache.org/log4j/)

Oneissuewithcomponentsoftware,bothopensourceandcommercial,istheextremevariance inquality.Somecomponentsareeasy tounderstandanduse;othersareinscrutableandimpractical.Inthischapter,Ilist thecapabilitiesthatdevelopersgenerallyassociatewithqualitycomponents.Youcanusethislisttoevaluateopensourceorcommercialcomponentsoftware.Ialsopresentaseriesoftipsandtechniquesforcreatingyourownarchitecturalcomponentswiththose

capabilitiesconsideredthemarksofquality.Theroleofarchitecturalcomponentsisillustratedinfigure14.1.

Figure14.1:UsingArchitecturalComponentswithinaLayeredArchitecture

COMPONENTQUALITYHigh-qualityarchitecturalcomponentshavethefollowingcapabilities:

ShortendevelopmenttimeandeffortShortenexpectedmaintenancetimeandeffortWorkinmanyapplicationsbecausetheyaregenericWorkasadvertised

These traitsaredesirableforanycomponentsoftware,whethercomponentsarecommercial,opensource,orauthoredbyyou.

A common guideline people usewhen judging software is: if they have toconsult amanual todobasic tasks, they judge the software “toohard touse.”You can use much the same standard when assessing component software. Iconsidercomponentsoftwaredifficulttouseifeitherofthefollowingistrue:

Youhavetoreadmorethantwopagesofmaterialtoinstallandconfigurethecomponent.

Ittakesmorethananhourfrominstallingtousingthecomponentforabasictask.

Acommonmistakepeopleusewhendesigningarchitectural components ischoosing a scope that is too large.A large scope usually results in a complexcomponentthatwill takealongtimetobecomeavailableandwillhavealonglearningcurve.Iusethe80/20rulewhenselectingfeaturestoimplementinanarchitecturalcomponent.Componentdesignersshouldn’tgetboggeddownwithfeaturespeoplewillrarelyuse.

MAKINGCOMPONENTSEASYTOUSEIf you’re evaluating component software, ease of use should be one of thedeciding criteria. If you’re creating an architectural component, there are anumber of things you can do (that many component developers don’t do) tomakeyourcomponenteasytouse.

Limittheinstructionsforbasictaskstoaone-pagecheatsheet.Youcanhavea more detailed document for sophisticated, unusual tasks. The longer thematerial developers need to read to get going, the higher the percentage ofdeveloperswhowillgiveupintheprocessandlookforsomethingelse.

Minimizethenumberofstatementsnecessarytoperformbasictasks.Oneofthechiefbenefitstousingacomponentiseliminatingcodeintheapplication.Aone-line call is ideal because it eliminates typing and reduces the number ofclassesandmethodsyouneedtolearn.

One way to achieve a one-line call is to rely on a static method. Thiseliminateshaving to instantiateanything.Thechoice tomake thatcallstatic ismorethanjustatacticalchoice.Asexamples,consideranyoftheUtilsclasses(e.g.,StringUtils,NumberUtils,ExceptionUtils fromApacheCommonsLang).Theseclassesarerepletewithconvenientstaticmethods thataccomplishmuchwithonelineofcode.

Minimizethenumberofargumentsnecessarytoperformbasictasks.Youcanaccomplishthisbyprovidingmultipleoverloads.Someofthoseoverloadshavesmallnumbersofargumentswithsensibledefaultsfortherest.

As an example, let’s consider the reflectionEquals methods in theEqualsBuilder for Apache Commons Lang. This class makes it easy toimplement equals()in any class. ReflectionEquals at a minimum requires two

arguments; thevaluesbeingcompared.However,moresophisticatedoverloadsoptionallyprovideyoucontroloverwhichfieldsareconsideredandhowmuchof the inheritance hierarchy is considered. As most don’t need the additionalcontrol,theseadditionalargumentsareoptional.

Separate the classes meant for public consumption from those neededinternallybytheAPI.Themoreclassesacomponenthas,thelongerittakestofindtheclasswiththefunctionalityyouwant.KeepingalltheseclassestogetherjustaddstothetimerequiredtolearntheAPI.

One way to solve this problem is to move classes not meant for publicconsumptiontoaseparatepackagethat’sdocumentedas“forinternaluseonly.”Usersdon’thavetowadethroughlow-levelclassestheydon’tneedyettofindthefunctionalitytheywant.

As examples of this, Apache Commons Logging separates internal classesinto a separate package (org.apache.commons.logging.impl). The Quartzscheduling package (http://quartz-scheduler.org) uses the same technique byplacing internally used classes into package org.quartz.impl. This techniqueconcisely informs users that they need not bother with the documentation fortheseclassesastheyareunlikelytoneedit.

Providesamplesthatareeasytocopyandincludeanindex.Makeiteasytofindasamplethatisclosetowhattheuserwants.Mostofuslearnbyexampleanddon’ttypeveryquickly;havingsomethingtocopyfromsavesuserstime.AgoodplaceforshortsamplesiswithintheJavaDoc.

As examples, both EqualsBuilder and HashcodeBuilder from ApacheCommons Lang provide usage examples in their JavaDoc that can easily becopied into your code and quickly be changed to suit your needs.As anotherexample, thePrimefacesproject,which isa libraryof JavaServerFaces (JSF)components, provides a demo site (http://www.primefaces.org/showcase-labs/ui/home.jsf)thatincludeseasy-to-accesssourcecodeforeasycopyingintoyourownproject.

LimitdependenciesonotherAPIs. Ioncewas forced to implementapoorlywritten scheduling component for a client (I wasn’t given a choice). Thiscomponentusedtwointernalcomponentsthatwerehardtouseandcomplextoconfigure. I’ve since learnedhow to avoid inflicting the samekindofpainonusersofmyopensourcecomponents:useinterfacestodecouple.

Check all arguments on all methods meant for public consumption andproduce clear errormessages for invalid inputs.Rather than degenerating into

derivativeexceptions(e.g.,nullpointerexceptions),put informationonhowtocorrect problems in the exceptions. For example, the error message “Invalidformat typeargument” isn’tasusefulasanerrormessage like“Invalid formattype ‘foo.’Valid types are the following constants in this class: PDF,HTML,XLS,andDOC.”Simplydisplayingtheerroneousvaluepassedtoamethodintheerrormessagemightshortenthetimeittakestodebugandcorrecttheissue.

Avoid throwing “checked” exceptions. Throwing “unchecked” exceptions,whichextendRuntimeException, ispreferred,because itdoesn’t force theuserinto as much try/catch logic. Not needing as much code to use a componentdefinitelymakesiteasiertouse.Theonlyexception(nopunintended)tothisisifthecallercanreasonablyprovidealternativebusinesslogicinresponsetotheexception; however, this is rare. For amore detailed discussion of this rathercontroversialconcept,seechapter9.

MAKINGCOMPONENTSEASYTOCONFIGUREANDCONTROLMinimizethenumberofpropertiesausermustconfigure.Somecomponentsuse a properties file, which is a file of key and value pairs, to manageconfiguration settings. These files are often used in conjunction with thejava.util.Propertiesobject.

Themoreproperties users need in order to choosevalues for runningyourcomponent, the longer and harder your component is to configure. You canalleviate thisproblembychoosing sensibledefaults for asmanyconfigurationproperties as possible. In addition, clear error messages for incorrectconfigurationscanmakeyourcomponentseasytouse.

MinimizetherequiredcomplexityofanyneededXMLdocuments.Themorecomplex thedocument structure, theharder thecomponent is toconfigureandcontrol. Jakarta’s Ant project is an excellent example of using XML fileseffectively. Ant is an XML scripting utility commonly used for applicationbuilds. Its scripting language is XML based, and its structure is simple andintuitive.AlthoughAnt has an extensive array of options, it also has sensibledefaults and good documentation. This open source project is available athttp://ant.apache.org/.

Produce clear error messages on invalid configurations. Components musthaveclearerrormessages.Nothingismoreaggravatingthantryingtofigureout

why code you didn’twrite is degenerating into aNullPointerException. Clearerror messages can make the difference in a developer’s perception of yourcomponent.

Providenumerousconfigurationfileexamplesthatareeasytocopy.This isespecially important if the component is capable of complex configurations. Isuggestprovidingbasicexamplesaswellascomplexones.

Limitinstallationandconfigurationinstructionstoaone-pagecheatsheet.Iftheinstructionsaretoolongandcomplex,itreducesthebenefitofusingthecomponent in the first place. Having an expanded document for completefunctionalityisfine,butusersdoingbasictasksshouldn’thavetoreadmorethanapageortwo.

OPENSOURCEALTERNATIVESOpen source alternatives have blossomed, somuch so that searching for opensourcealternativesforagivenneedhasbecomeacomplicatedtask.

Most organizations accept open source usage with guidelines. Manycompanies will define open source licenses that may be used (e.g., ApacheLicense,Version2.xandothers).Shouldadesiredproductnotadoptastandardlicenseverbatim,mostcompaniesprovideanapprovalpathsothatlicensescanbeevaluatedbytheirlegaldepartment.

Someorganizationsarewaryofusingopensourceproducts.Theperceptionis that theseproductsareessentiallyunsupported.Andwhile thepriceofopensource technologieswill fit intoanycorporatebudget,manyorganizations likethesecurityofhavinga technicalsupportnumber tocallwhenproblemscomeup.Therearereallytwoissueshere.Thefirstisthepracticalissueofbeingabletosolvetechnicalproblemswithanopensourceproducttogetyourapplicationsworking,andkeepthemworking.Thesecondishavingsomeoneelsetoblame(orpotentiallysue)ifyourproductselectiondecisionturnsouttobeabadone.Usually,companieswithanti-open-sourcepoliciesaremoreworriedaboutblameassignment.Thankfully,resistancetoopensourceusageappearstobedeclining.

ResolvingTechnicalIssuesThe following are some steps I’ve gone through to solve problemswith opensourcecomponentsoftware.Step1isthesimplestsolution.Ifthatdoesn’twork,you’llneedtoperformstep2beforetryinganyoftheremainingsteps,whicharelistedinorderofsimplicity.

Step1:Searchtheproduct’sbuglist.True,manyopensourceproductsdon’thaveformalsupportorganizations.However,manyproductsprovideaccesstoabuglistandprovideawaytoreportidentifiedbugs.Often,theproblemyouarehavinghasbeendiscoveredandreportedbysomeoneelse.Perhapsaworkaroundorsolutionhasbeenposted.Step2:SearchtheInternet.OftengenericInternetsearcheswillrevealpostingsofotherswhohaveencounteredthesameproblem.Often,solutionswillbepostedinthesamenewsgroupsorblogs.Step3:Upgradetothelatestversion.Ifanewerversionoftheproductisavailable,agoodtimetotryitoutiswhenyou’retryingtoresolveatechnicalissue.Maybetheproblemistheresultofabugthatsomeonecaughtandfixed.Often,theworkinvolvedinupgradingisjustincludingamorerecentjar(s)inyourclasspath.Step4:Evaluatecompetingproducts.Ilookforcompetingopensourceproductsthatdothesamething.IfIcaneasilyswitchproducts,I’lltrythat.IoncehadanissuewithanopensourceJavaFTPclientAPIthathadamemoryleak.Whenanewsgroupsearchdidn’trevealananswertomyproblem,IswitchedtoanotheropensourceFTPclientAPI.Step5:Debugyourtestscenario.Althoughthisisn’tapleasanttask,itinvariablyenablesyoutodeterminetherootissue.Onceyouknowwhattheproblemis,youcanstartlookingforaworkaround.Step6:Modifycomponentcodetofixtheproblem.Thisshouldbetreatedasanoptionoflastresort.Ifyouuseanalteredversionofanopensourceproduct,you’llbeonyourownforprobleminvestigationsafterthat.You’llneverknowiftheproblemyou’reexperiencingwasaresultofaproductbugortheresultofyourchange.Ifyouhavetomodifythecode,takethetroubletoreportthebugandsolutiontothedevelopersthatproducedthecomponent.Mostdevelopersofopensourceproductswouldreleaseanewversionwithabugfix.Assoonasyoucangettoanunalteredversionofthecomponentthatworksforyourapplication,youshoulduseit.

MitigatingPoliticalRiskThesecondissuesurroundingtheuseofopensourcecomponentsoftwareisthecorporateneed tohavesomeone toblameif thechoiceofopensourceproductdoesn’tworkoutaswellasintended.Ican’tthinkofawaytocompletelysolve

theissue,butIcanthinkofmanywaystomitigatetherisk.Suggest a commercial software component along with open source

alternativesandkeepanydocumentationofthedecision.Thistacticeffectivelymakesthecomponentdecisionagroupeffort.Ifanopensourcedecisioniseverquestioned,youcanframetheissueasagroupdecisionandpointtobudgetaryadvantages.

Trackwhichopensourceproductsyouuseandkeepsourceaswellasbinarydistributions.Youwon’twanttofindoutatthetimeyou’rehavingtroublethatthesource for theversionyou’reusing isno longeravailable.Asa last resort,youcantrytofixtheproblemyourself.

Identify competitors to the open source product. This shortens the time ittakestoswitchcomponentsshouldyouneedtodoso.Italsohelpsdocumentduediligenceintheproductsearch.

COMPONENTUSAGEGUIDELINESWhetherathird-partycomponentisopensourceornot,oneofyourgoalsshouldbeminimizingbusinessrisk.Alargepartofthatiskeepingswitchingcostssmallsothatifamistakeismade,itwillbeeasiertocorrect.

Minimize the classes directly using third-party components with directcompetitors.Productswithdirectcompetitorsareproductsthathaveafocusedfeaturesetofferedbymultipleproducts.Forexample,loggingproductsfallintothis category. Developers have conflicting opinions about which loggingpackage should be adopted.While themain players areApacheLog4J, Slf4J,and the logging framework within the JDK itself, there’s no consensus as towhichpackageshouldbeutilized.Giventhis,Iusuallyhaveapplicationcodeusea logging proxy that leverages one of these logging frameworks underneath.Should there be a need to change logging packages, the use of third-partyspecificcodedoesn’tpervadetheapplications.

Youcanisolatedependenceonaparticularproductbycreatingaproxyclass.Continuing with the logging product example, I often create an applicationLoggerclassthatservesasaproxyforanunderlyingloggerprovidedbyoneofthe loggingproducts.As application code relies solely on the proxy class, it’sfairly easy to change logging products if need be as it’s only the proxy thatwouldneedtobechanged.

Another example of this concept is scheduling packages. Quartz(http://quartz-scheduler.org) is the product I usually leverage, but there are

several competing products available. If enterprise scheduling considerationsarise, it’s possible that the scheduling product might be changed. Usually, Iprovide a base class that implements any needed interfaces required by thescheduling package. Hence, this base class is the only class that directlyinterfaces with the scheduling package and can easily be changed to use adifferentpackageinstead.

Somethird-partyproductshavetoobroadascopeforaproxytechniquetobeeffective. For example, Apache Commons Lang, Collections, and BeanUtilspackagesprovideutilitylibraries.Theworkinvolvedtocreateproxyclassesforalltheutilitieswouldbeextensive,asthescopeoftheselibrariesisverybroadand would provide very little benefit since these products have no directcompetitors.

You can use this technique with virtually any software component.Rememberthatyoualsolimitrelianceonanythird-partycomponentexceptionclassesso thatyourapplicationrelieson internalclasses,notexternalones.Toaccomplishthis,havetheproxysurroundusageoftheunderlyingproductwithatry/catchblock.Anycomponent-basedexceptionsgeneratedcanbeconvertedtoapplication-based exceptions and prevent unwanted reliance on third-partyexceptionclasses.

CHAPTER15

APPLICATIONARCHITECTURESTRATEGIES

To ensure that your applications have internal consistency, you need toestablish strategies from the outset for logging, exception handling, threading,and configurationmanagement.Most developers have preferences for each ofthese areas. If your team has many developers and you let them use theirpreferences, you will create an application that is internally inconsistent andharder tomaintain.Thischapteroffersstrategiesforeachaspectofapplicationarchitecture.Inthissection,I’vearticulatedexamplesofstrategiesI’veusedinthe past. Once you establish the strategy, don’t be afraid to refine it withadditionaldetailtosuittheneedsandcomfortlevelofyourdevelopers.

LOGGINGSTRATEGIESApplication classes should not depend on a specific logger. General-usecomponents should be able to use any logging package an application adopts.Thiscanbedonebyhavingoneclass in theapplicationactingasa logproxy,delegating the logwrite to Log4J, JDKLogging, or one of the other loggingpackages. Listing 15.1 is an example of an application logger proxyimplementation.

Listing15.1:SampleLogProxyUsingSLF4J

TheApacheopensourcecomponentsoftwareCommonshasapackagecalledCommonsLoggingdesigned to fill this need.Unfortunately, it is rather heavy(despitebeingbilledasintentionally“lightweight”)andnotveryeasytouse.Itrequires an XML parser and has amore complicated configuration scheme. IconsiderCommonsLoggingmorehasslethanit’sworth.

The open source product Simple Logging Facade for Java (SLF4J) is anexcellentproductthatmeetsthisneed.ThisproductisagenericproxyforLog4J,JDKLogging,CommonsLogging,andotherloggingproducts.It’seasytoinstalland use. I’ve started using SLF4J in my own open source projects. I still,however,usealoggerproxyclass,suchaslisting15.1,forbusinessapplicationsasthisspaceisstillchangingandevolving.Manypopularopensourceproducts,suchasHibernate,ActiveMQ,andothershaveadoptedit.

Limitcodingforloggingmethodstooneline.Logging isdonesofrequentlythat you’ll save a lot of time by reducing the code it takes to log. Slf4Jintroduced a nice feature that assisted developers in reducing logging codebyproviding basic message formatting features. For instance, consider the

followinglogexample:

Listing15.2:SampleLogIllustratingFormattingFeature

logger.debug(“Applicationidsetto{}”,applicationId);

Thisfeatureaccomplishescodereductionbyformattingthemessageforthedeveloper. It also reduces risk as the developer code contains fewer operatorsanddoesn’thavetocheckfornullvaluesinformattingthemessage.

Also,forperformancepurposes,itisnotuncommontocheckifloggingissetto debug before issuing a debug log message to improve performance. Slf4Jprovides this check automatically without developers having to code theadditionalconditional.

Notethattheloggerproxyinlisting15.1supportsSlf4Jmessageformattingcapabilities.WereItoswitchfromSlf4Jtoanotherloggingpackage,theloggerproxywouldhavetoprovidesimilarmessageformattingabilities tokeepfromimpacting the application code that uses it. Message formatting capabilitiesreduce risk by eliminating custom logic to format loggingmessages.Messageformattingalsoprovidesperformanceimprovementbyonlyformattingmessagesmeetingthecurrentloglevelsetting.Forinstance,ifyourloggerisconfiguredtoprovide info leveloutput,debugmessageswillnotbe formattedas theyaren’tneeded.ThebenefitsofmessageformatsupportarelargeenoughthatIassumethe risk of a slightly higher switching cost, should the need to switch loggingpackagesarise.

Bundleneededinformationwithexceptionsthatyouthrow.Oneofthemainreasonsforloggingistoprovideinformationneededtoresolveabugresultinginanexception.Thisadditional loggingcodeaddsadditionalrisksinceexceptioncodeisn’t typicallytestedasthoroughly.Hence,there’susuallyalargerchanceof excepting (e.g., from a NullPointerException) during exception messageformattingthanwithnon-exceptioncode.

ApacheCommonsLangprovidesacontextedexceptionabilitystartingwithV3.0thatreducesthisriskbymakingiteasyandlessriskytoincludeadditionalinformation with the exception itself (see classes ContextedException andContexedRuntimeExceptionfromCommonsLang).Thisadditionalinformationwill bepresentwhen this exception is logged.Consider the example in listing15.3.

Listing15.3:SampleContextedExceptionExample

thrownewContextedRuntimeException(“Errorcreatingapplication”,exception).addContextValue(“applicationid”,applicationId).addContextValue(“customerid”,customerId);

When the exception in listing15.3 is logged, the context labels andvalueswill automatically appear in the log, along with the error message and stacktrace.Notethatapplicationcodedoesn’tincreaseriskofaderivativeexceptionbyaddingconditional logging logicor formatting logic.Note that if itweren’tforthecontextedexceptionability,developerswouldhavetoaddloggingcodetosupplytheinformationneededtoresolvethebug.

Logtransactionexceptionsonlyonce.Loggingexceptionsmultipletimeswillgreatlyinflateyourlogsandmakeaspecificexceptionpertainingtoareporteddefectmuchhardertofind.Youcanavoidtheproblemofrepeatinglogmessagesby logging exceptions at the entry points only. For example, it’s easy toimplementaservletfilterthatwilllogexceptionsforanywebtransactions.Thisensures thatexceptionsare loggedonlyonce.Thisadviceassumes thatyou’vebundled any additional information needed to resolve the error with theexception itself, as described earlier in this chapter. Listing 15.4 illustrates aservletfilterofthistype.

Listing15.4:LoggingServletFilterExample

publicvoiddoFilter(ServletRequestrequest,ServletResponseresponse,FilterChainchain)throwsIOException,ServletException{

try{chain.doFilter(request,response);}catch(Throwablet){logger.error(“WebTransactionError”,t);ServletUtils.reThrowServletFilterException(t);

}

}

Source:Classnet.admin4j.ui.filters.ErrorLoggingFilterfromAdmin4J(http://www.admin4J.net)

This technique reduces application code and increases the chance that

generated exceptions are logged. Furthermore, if you leverage the Admin4Jproduct, which has an error handling filter, you’ll get the request URI and adumpofanyrequestandsessionattributesatthetimeoftheexception.Inotherwords,youcanleverageanopensourceproducttoaccomplishthis,ratherthancreatingyourownservletfilterforthispurpose.

Incidentally,you’llneedtoprovidesimilararchitecturalsupportforbatchjobclasses, EJB classes, andmessage-driven beans. Leaving exception logging toapplicationcodeincreasestheprobabilitythatanexceptiondoesn’tgetproperlylogged.

Do not commingle transaction logs with normal application logging.Transactionlogs(e.g.,userFredchangedtheaddressofcustomerAcme)haveadifferent purpose. Often, transaction logs are needed by normal businessprocesses and really aren’t directed at product support.Most logging productswillallowyoutodirecttransactionlogstoaseparateoutputforthispurpose.

Notethatlogretentionandstorageconcernsareacompletelyseparatetopic.Mostloggingproductssupportstoringlogsinavarietyofformats,includingfileordatabaseformats.Applicationcodeshouldonlybeconcernedwithissuinglogmessages,notwiththespecificsofhowtheyarestoredorforhowlongtheyareretained.

Application architects need to clearly articulate the logging strategy fordevelopers.Belowisasimpleexampleofsuchastrategy:

SampleLoggingStrategy

Usemyapp.util.Loggerforalllogging.DonotuseSystem.out.println().Donotlogerrormessagesdirectlyinapplicationcode.Relyontheapplicationarchitecture(e.g.,errorhandlingservletfilter)tologforyou.Warnings,informational,anddebugmessages(i.e.,errorsnotsevereenoughtowarrantthethrowingofanexceptionbutthatwouldbeusefultoadeveloperfixingbugs)canbeloggedanywherefromanylayer.Whenusingloggingtooutputinformation,useloggermessageformattingfeatures,insteadofemployingcustomformattinglogic,toreduceapplicationcodeandtheriskofproducingderivativeexceptions.Donotusethegeneralloggingfacilityasatransactionlog.

EXCEPTION-HANDLINGSTRATEGIESValidateallargumentsexplicitly inallpublicmethodsandconstructors inall public classes. Validating all arguments for publicly consumed methodsprevents derivative exceptions. Derivative exceptions are those reported wellaftertheerroroccurred.It’sanall-too-commonerrortopassanullargumenttoamethod accidentally, only to find that a NullPointerException was generatedwhentheclass thatwascalled(directlyor indirectly) tries touse theargumentandisn’texpectingthenullvalue.

While it’s possible to get the class, method, and line number where theNullPointerException occurred, the actual error occurred well before, at thepoint where the null value originated. This often is in an entirely separatemethodandclassfromwhat’sreportedinthestacktraceandcantakesignificanttime to track down, especially if the code is complex and multiple variablescould have generated the exception. Typically, derivative exceptions like thistakemoretimeandefforttofixbecausetheerrormessageandinformationdon’tmake the problemclear.Had themethodgenerated an exceptionmessage like“Thenameargumentmaynotbenull.”theerrorwouldbeeasiertofindandfix.

Argument validation enables you to report an errorwith a clearermessagethan youwould otherwise get. Null arguments are commonly validated. If anargument has to conform to a specific value set (for example, a docTypeargument that allows only “pdf,” “xls,” and“txt” values), the value should bevalidatedaswell.ItypicallyleveragetheValidateclassfromApacheCommonsLangforthispurpose,asillustratedinlisting15.5.

Listing15.5:ArgumentValidationExample

publicBasicTaskTimer(Stringlabel,Collection<DataMeasure>dataMeasures){Validate.notNull(dataMeasures,

“Nulldatameasurecollectionnotallowed.”);Validate.notEmpty(label,“Nullorblanklabelnotallowed.”);this.dataMeasures=dataMeasures;this.label=label;

}

Source:Classnet.admin4j.timer.BasicTaskTimerfromAdmin4J(http://www.admin4J.net)

Trend toward unchecked exceptions. This reduces application code byeliminating try-catch logic requiredbycheckedexceptions.Several commonly

used open source projects, such as Hibernate and Spring, have adopted thisapproach. At the time the first edition to this book was released, this was acontroversial ideawithzealotsonbothsides.This idea ismuchmoreacceptedandutilizedtoday.

Includegeneralcatchesforthrownexceptionsatallentrypoints.Thereasonfor this is so that theseexceptionscanbe logged.Thisadvice is related to theloggingadvicegivenearlierinthischapter;Iwon’trepeatthatmaterialhere.

Use native JDK exceptions before creating your own. There’s no need toreinventthewheel.Manydeveloperswon’tevencheckifthereisanappropriateJDK-defined exception that they could use in lieu of creating an application-specific exception. As a real-world example, I’ve seen a developer create anexception called NullValueException that was thrown when a method wasprovided a null argument instead of a valid value. IllegalArgumentException(fromjava.lang)wouldhavebeenabetterchoice.

Limit thenestingdepthofa try/catchblock to two. (Manyof you, I know,wouldcampaignforone.)Ifyouneedmore,removetheinnerblocksofcodetoseparate private methods for readability. In addition, fixing bugs in nestedtry/catch scenarios can be difficult. As an aside, the need for deeply nestedtry/catchlogicusuallyindicatesaneedtorefactorthissectionofcode.

Don’t catch exceptions and do nothing with them. For programmaticconvenience,somedeveloperscatchexceptionsbutfailtocodethecatchblock.Thispracticeeliminatesacompilererrorbutmakesthecodehardertomaintain.Manytimes,swallowingexceptions leads toderivativeexceptions lateron thatarehardertofindandfix.Ifyoucatchanexception,dosomethingwithit(e.g.,convertittoacontextedruntimeexceptionandincludeinformationneededtofixtheunderlyingbug).

Never put a return statement in a finally block. If something throws anexceptionwithinatryblock,thefinallyblockisexecutedbeforetheexceptionisthrown. Ifyou issuea returnstatementwithin thefinallyorsomethingexceptswithinthefinally,theoriginalexceptionwillneverbethrownandneverbeseen.Thiswillincreasethetimeandeffortneededtodebugaproblem.

Thearchitectandprojectmanager shouldestablishanexception-handlingand logging strategy before coding begins. Developers often have personalpreferencesforexceptionhandlingandlogging.Ifyoudon’tdefineastrategyfor

exception handling and logging, developerswill choose their own, and you’llhavenoconsistencyacross theapplication.Eventually,whendifferent sectionsoftheapplicationareintegrated,conflictswillarise.Inaddition,itwillbemoredifficultforanoutsidertomaintaintheapplication.

For example, suppose one developer adopts the philosophy of loggingexceptionswhenthey’reinstantiated,whileanotherexpectsloggingtooccuratthe deployment level. When all code is integrated, some errors will gounreported,whichwillgreatlyincreasetestingandmaintenancetime.

Oneofthemostvaluablepiecesofinformationgeneratedbyanexceptionisthe stack trace of the root exception. The stack trace indicates where theexceptionwasthrowndefinitively.Insomecases,youwillevengetanexactlinenumber.Ideally,youshouldseethestacktraceof therootexceptioncombinedwithmoredescriptivecontext information.Leveraging thecontextedexceptionfeatureofApacheCommonsLangV3.0andaboveisgreatforthis.

Youalsoneedtoenforceyourexception-handlingstrategy.Iusegroupcodereviews as a mechanism for enforcement and education. Code reviews, ifconducted properly, are very constructive. Developers can learn a lot byreviewingthecodeofotherdevelopers.Reviewsalsomakeitmoredifficult toskirt establishedpolicy, like an exception-handling strategy.Additionally, codereviews allow you to identify any shortcomings in the exception-handlingstrategyandmakeadjustments,ifnecessary.

SampleException-handlingStrategy

UseValidatefromApacheCommonsLangtocheckallmethodargumentsonpublicmethodsandconstructors.Alwaysincludeenoughinformationinthemessageoftheexceptiontoduplicatetheconditioninatestingenvironment.AllapplicationexceptionsshouldextendContextedRuntimeExceptionfromApacheCommonsLang.Newapplicationexceptionproposalsshouldbereviewedbytheapplicationarchitect.Alltry/catchblocksinthebusinesslogiclayerorthedataaccesslayershouldnotinterferewiththethrowingofuncheckedexceptions.Throwtheexceptiontothecallerinsteadandrelyontheapplicationarchitecturetocatchandproperlyhandletheexception.

ASYNCHRONOUSTASKSTRATEGIESMostapplicationshavetasksthatrunasynchronously(e.g.,doesn’tforceauserto wait). These tasks can include scheduled “batch” work and long-runningtasks.JavaEEapplicationsarenoexception.Fortunately,thereareseveralopensource products that provide batch job capabilities for Java applications. Iusually leverage theQuartz Job scheduler (http://quartz-scheduler.org/) for thispurpose.

It’s generally preferable to leverage a product to manage asynchronouslyrunning tasks rather than write threading code yourself. This area of Javaprogrammingtypicallytakesthemostseniordevelopersandisverydifficult toget right.Bugs frommulti-threadedcodecanbe themostdifficult to find andfix. It’s also not an area of programming where you want junior developersinvolvedastheriskpotentialishigh.

Aswith other third-party components, I usually provide a proxy batch jobthat can be used by a scheduling package. This will reduce switching costsshouldchangingtheschedulingproductusedbecomenecessary.Listing15.6isanexampleofaQuartzbatchjobbaseclass.Theideaisthatapplicationextendsthisclassfillingintheexecute()methodthatcontainslogicforthebatchworktobedone.Notethatthebaseclassprovidesawayfortheapplicationtoschedulethebatchjobforimmediateexecution.Shouldswitchingschedulersbeneeded,it’sonlythebatchjobbaseclassthatwouldneedtochange.

Listing15.6:SampleBaseJobClassDesignedtoUsetheQuartzScheduler

Source:srcj2ee/architect/handbook/chap14.AbstractBatchJob.java

As with logging and exception handling strategies, application architectsneed toprovideguidance for asynchronous tasks.Asample strategy similar towhatIuseinbusinessapplicationsfollows:

SampleAsynchronousTaskStrategy

Extendmyapp.util.AbstractBatchJobforallasynchronoustasks.Donotspawnasynchronousthreadsindividually.Donotlogyourownexceptions;thearchitecturewillensurethatanyexceptionsyouthrowareproperlylogged,alongwithspecificsaboutthejobandanyexecutionparametersused.Donotmanageyourowntransactions;acommitwillbeexecutedonsuccessfulcompletionandarollbackwillbeissuedshouldanexceptionbegenerated.

CONFIGURATIONMANAGEMENTSTRATEGIESMost Java EE applications have some configurable properties, such asconnection pool names, group e-mail addresses, and much more. Regardingconfiguration,thereareseveraltopicstoaddressformostJavaEEapplications:

Determiningvaluesforconfigurationitemsfromtheenvironmentorsomedatasource(e.g.,propertiesfile).Makingvaluesforconfigurationitemsavailabletoapplicationclasses.Documentingconfigurableitemsfordevelopers.

Makingconfigurationvaluesavailabletoapplicationclassescanbeassimpleasdeclaringaconfigurationclasswithstaticaccessorsandmutatorsrepresentingindividualapplicationproperties.AnexampleofsuchaconfigurationclasscanbeseenintheAdmin4JproductanditsAdmin4JConfigurationclassexcerptedinlisting15.7.

Listing15.7:ExampleConfigurationClassfromAdmin4J

Source:Admin4Jproductclassnet.admin4j.config.admin4JConfiguration

Applicationclassesusetheconfigurationaccessorstoretrieveconfigurationvalues. A class responsible for interrogating the environment and reading theconfiguration from some external source will use the mutators to setconfigurationvaluesatstartup.Notethestaticblockinlisting15.7thatreliesonclassPropertyConfiguratortointerrogatetheenvironmentandsetconfigurationvalues.Asthisisastaticblock,itwillexecutewhenthisclassisfirstreferencedbytheapplication.

Javadocintheconfigurationclasscandescribethelistofconfigurationitemsand the purpose of each for developers. Some developers prefer to retrieveconfigurationvaluesfromtheenvironmentdirectly.Thelargestdisadvantagetothisisthatitleavesnodiscreteplacewhereallpossibleconfigurationitemsfortheapplicationaredocumented.

The fact that the act of configuring the application is separate makes it

possible to support multiple forms of configuration at some point withoutincreasing complexity now.An example of this is theApache Log4J product,which will allow configuration through either a properties file or an XMLconfigurationdocument.

Somedevelopersliketoputapplicationconfigurationitemsintheapplicationdatabaseasthat’smoreeasilychangedatruntimeinmostorganizations.WhileIunderstand the appeal, given the bureaucracy inmost organizations, I usuallyavoidstoringconfiguration items in theapplicationsdatabaseas itcomplicatesbackloads(copyingaproductiondatabasefordevelopmentortestingpurposes).It’s common to backload application data from production to a testingenvironment periodically so developers are working with current data. Ifconfiguration items are stored in the application database, production valuesmight be used by mistake. This can cause problems in production if thoseconfigurationitemsidentifyproductionfilesorresources.

There are configuration products that will provide support for gatheringconfigurationinformation.OnesuchproductisApacheCommonsConfiguration(http://commons.apache.org/configuration). Formost Java EE applications, thelist of configuration properties is small; involving a separate product to readconfigurationinformationisusuallyoverkill.

SampleConfigurationGuidelines

Defineallconfigurationvaluesaspropertiesinclasscom.myorg.myapp.Configuration.Ensurethatlogictosettheconfigurationvalueispresentinclasscom.myorg.myapp.Configurator.Ifpossible,ensurethattheconfiguratorassignsadefaultvalueforthepropertyincaseit’snotspecifiedinaparticularruntimeenvironment.Throwanexceptionintheconfiguratorshouldtheconfigurationvaluenotbesettoanallowedvalue.Pleaseincludetheinvalidvalueandablurbaboutwhatvalidvaluesareintheerrormessage.

Another exampleof establishing strategies for exceptionhandling, logging,andcodingconventionsdrawnfromtheopensourcecommunitycanbefoundathttp://commons.apache.org/lang/developerguide.html.

This example is the coding conventions established for the open sourceproduct Apache Commons Lang. The URL above is an excellent example of

formally establishing the architectural policies discussed in this chapter andcommunicating them.While theadvicemaydiffer fromwhat Iprovidehere, Istill provide it as an example because establishing clear guidelines fordeveloperstofollowismoreimportantthantheminordisagreementsIhavewithsomeofthelineitems.

CACHINGSTRATEGIESCaching, keeping frequently used data in memory, is a common tactic forperformance benefit. Basically, caching trades memory for CPU and diskutilizationandspeed.Aswithallstrategies,cachinghasrisksaswellasbenefits,so it should only be used in cases where you get material performanceimprovement.Lowvolumeapplicationsmaynotneedto implementcachingatall,butit’scommonenoughthatitdeservesfocus.

For caching in application code, the algorithm is usually simple. I’ll use aprimitive ExpiringCache class as a usage example; ExpiringCache source isincluded in the source bundle. Lest you think I custom-coded a cache,ExpiringCache wraps caching functionality in Guava(https://code.google.com/p/guava-libraries/ ). Consider the usage example inlisting15.8.

Listing15.8:ExampleCacheUse

privatestaticExpiringCache<Long,String>cache=newExpiringCache<Long,String>();.....Stringvalue=cache.get(key);if(value==null){//Putcodetolookupthevaluecache.put(key,value);

}

NotethatsomeJPAimplementationsprovidecachingabilities.Forexample,Hibernateprovidescachingabilities thatyoucanuse insteadofcustomcodinguseofacacheasI’vedoneabove.

AscachingworksbyavoidingI/O,itcarriesastaledatarisk.Thatis,datainthecachemighthavebeenchangedatthesourceandthatstaledataisbeingusedbytheapplicationforprocessing.Forexample,ifyoucachedatafromaremotewebservicecall,it’spossiblethatthedatamayhavechangedsincethelastread.

Inthatcase,yourapplicationwillbeusingstaledata.Thatisalsopossibleifyoucachetheresultofadatabaseread.

Ascachingtradesmemoryforspeed,theadditionalmemoryrequirementsforcachesyouconfigureneedtobeconsidered.GuavaandanotherpopularcachingpackageEhcache(http://ehcache.org/)providewaystolimitthenumberofcacheentriestomitigatetheriskofcachingcausingamemoryshortage.

Since I mentioned using caching features of JPA implementations (e.g.,Hibernate),IshouldpointoutthatimplementingaJavacachefordatabasereadsis usually redundant. Relational databases have built-in caching ability and ifproperly configuredwill cache frequently used data. I’ve had occasion to testHibernatecachingextensively,andI’vediscoveredthatunlessyourdatabaseispoorlyconfiguredoryournetworkbetweentheapplicationserveranddatabaseserverhasbadperformance,Hibernatecachingdoesn’tmakeanydifference.Ifyouhaveapoorlyconfigureddatabaseorapoorlyrunningnetwork,it’sbettertofixthem,ifpossible,astheywouldbetherootcause.

FURTHERREADINGJohnson,Rod.2002.ExpertOne-on-One:J2EEDesignandDevelopment.Indianapolis,IN:WroxPress.

Lea,Doug.2000.ConcurrentProgramminginJavaSecondEdition:DesignPrinciplesandPatterns.Boston,MA:Addison-Wesley.

SECTIONIV

TESTINGANDMAINTAININGJAVAEEAPPLICATIONS

Oncetheworkofbuildingtheapplicationisfinished,thetechnicalarchitectisoftenaskedtoleadperformance-testingactivitiesandensurethattheapplicationisproductionready.Atthisstage,thearchitect’sprimaryobjectiveisimprovingapplication performance, stability, and operational readiness. To achieve thisgoal, the architect needs to conduct performance tests andmake performanceimprovements, recommendchanges tomakeapplicationseasier tomonitorandsupport,andidentifycandidatesforcoderefactoring.

Thissectionguidesyouthroughtheseactivities.Init,youwilllearnhowto:

Establishcodingguidelinesforfunctionaltestcases.Conducteffectiveperformancetests.EffectivelyprofileyourapplicationtoimproveitsuseofmemoryandCPU.Improvesupportabilityforyourapplications.Recognizewhencodeneedsrefactoring.Adaptsoftwarearchitectureprinciplestonewtechnologies.

CHAPTER16

TESTINGGUIDELINESANDSTRATEGY

Thereareseveraldifferentlayersoftesting:

Unittesting:teststhatverifythecorrectnessofapublicorprotectedmethodorconstructorofaspecificclass.Integrationtesting:teststhatverifythatanindividualsoftwarefeatureorfunctionworksasintended.Systemintegrationtesting:teststhatverifythatthesoftwareproductasawholefunctionsasintendedandinterfacescorrectlywithexternalapplicationsorsoftwarecomponents.Useracceptancetesting:testsconductedbyendusersorend-userrepresentativestoensurethatdeliveredsoftwareworkscorrectlyanddeliversonitsintendedbusinesspurpose.Performancetesting:teststhatthesoftwareproductscalesandthatperformanceisacceptablewhenoperatingunderafullworkload(e.g.,expectednumberofusers).

Asanapplicationarchitect,youneed toensure that testingguidelinesexistfor the project at each of these levels. Typically, the application architect’srecommendations on these items will be sought. While management mightoverrulepartsof the recommendations,given that they require resources tobeimplemented, it is often the case that the architect’s recommendations areacceptedoutright. In thischapter, Iwillelaborateonmyviews regardingeachformoftesting.

UNITTESTINGGUIDELINESUnittestingoperatesontheprinciplethatfindingdefectsearlierintheprojectisusually cheaper, in that fewer people are impacted by the defect before it’s

identifiedand fixed.Once inplace, ithelpsprevent futuredefectsbyallowingdevelopers tomake changeswith a reasonable degree of confidence that theirchangeswon’tbreakanything.

Damage from bugs occurs in many forms. A bug discovered late in thetestingprocesscanimpactaprojecttimeline.Abugdiscoveredafterdeploymentcan damage users’ faith in the system and the development team. And fixingbugs late in the process involves more manpower. At that point, the fix caninvolve not only the developer but an entire testing team (if your project hasthem,andmanydo).

Bycontrast,newsofabugcaughtearlyintheprojectpassesnofurtherthanthedevelopmentteam.Thetestingteamandenduserswon’tbedirectlyinvolvedinverifyingafixtoabugtheyhaveneverexperienced.

Unittestingguidelinesneedtoanswerthefollowingquestions:

Whatlevelofcodeunittestcodecoverageisconsideredadequate?Whichclassesandmethodsrequireunittests?WheredoIputmyunittestssothattheycanbeeasilyfoundandusedbyotherdevelopers?Howoftenaremyunittestsexpectedtoberun?Whofixesthemwhentheybreak?Ifmyunittestsrequireexternalresources(e.g.,relationaldatabasesorexternalapplications),whatenvironmentaretheyexpectedtorunin?Whatunittestingtoolsareinthetechnicalstackandareavailableforuse?

ThisiswheremostpunditsmakethesalespitchforTestDrivenDevelopment(TDD); that is, write unit tests before writing the code itself. In this way,developers ensure a high level of unit test coverage and ensure that theyunderstand the requirementsofwhat theyareabout tocode.Thispracticealsoguidesdeveloperstowardwritingcodeinsuchawaythat itcanbeunit tested.Most pundits make the claim that anything less than 100 percent unit testcoverage (that is, all lines of code are tested at least once by a unit test) isunacceptable.

On the other side of the argument, if youwrite unit tests afterwriting theunderlying functionality, your tests are more likely to address the higher-riskareasofyourcode,asyou’llwritethematapointwhenyouunderstandthemostabouttheproblemyou’retryingtosolve.

Ithinkit’smoreimportanttospecifywhatlevelofcodecoverageisrequiredthan to micromanage exactly when in the development process a developerwritesthecode.

Whatlevelofunittestcodecoverageisadequate?Mostorganizationswon’tfund100percentunittestcoverage.Inanycase,itdoesn’tcompletelyeliminatebugsasitonlyteststheinputsthatarescriptedintheunittests.Whileunittestsallowdevelopers to refactorcodemore safely, it alsomeans thatmorecode isinvolvedforeachchange(youneedtochangetheexpectationsintheunittestsalongwith changing the behavior of the application), thus leading to a longerdevelopment time for that change. Pundits would argue that additional timespentmaintainingtheunittestcaseswillbemadeup,becauselesstimewillbeneededtofixbugs,giventhattherewillbefewerbugstofix.

If you’re curious as to the code coverage percentage experienced by otherapplications,checkoutNemo(http://nemo.sonarsource.org/).Nemoissponsoredby Sonar and presents Sonar statistics, including code coverage, for severalpopular open source projects. You’ll quickly see that the code coveragepercentage varies widely from project to project. If you’re skeptical that lessthan100percentcodecoveragemightbeacceptable,visitNemo;you’llfindthatmostprojects(includingsomeverysuccessfulprojects)operatewithwellunder100percentunittestcoverage.

There are products thatwillmeasure unit test coverage for you.One suchproduct, Sonar (http://www.sonarsource.org/), is open source and freelyavailable. Sonar also provides awide variety of softwaremetrics to help youmeasurethequalityofyourapplications.AnotherproductthatwillmeasureunittestcoverageisCrap4J(http://www.crap4j.org/).

Iusuallyrecommendrequiringatleastonepositiveandonenegativeunittestcaseperpublicandprotectedmethod—fordataaccessandbusinesslogiclayerclassesandforallutilityclasses.Apositive testcase isonewhere themethodcompletes normally. A negative test case is where the method issues anexception(e.g.,forinvalidinput).

This is far from100 percent coverage, but it’s simple to follow. Simple tofollowmeansthatit’smorelikelytobefollowed.Whileitispossibletoexpressthisrequirementintermsofacodecoveragepercentandarrangeforautomatedtestingtomeasurethispercentage,thattakesmoretimeandshiftsmanagementworkonto thedeveloper. In all honesty, utility classesprobably shouldhave ahigher testcoverageas theyareoftenmorewidelyused thanbusiness logicor

dataaccessclasses.At a management level, I try to ensure that unit tests exist for the most

commonlyexecutedcodeand themost complexcode.BothSonarandCrap4Jwillalsoprovidecodecomplexitymetricsinadditiontocodecoveragemetrics.Also,ifasectionofcodecontinuestoappearindefectreports,ensuringthatthiscodehasanadequatetestharnessisawaytoreduceitsdefectrate.

Wheredo Iputmyunit tests?This shouldbe establishedby the applicationarchitectwith input fromalldevelopers. Iusuallydefinea“test”source folderforeveryapplicationwhere theunit tests reside.Most IntegratedDevelopmentEnvironments (IDEs) have rich unit testing support for Junit. For example, inEclipse,youcanrightclickonasourcefolderandrunallJunittestscontainedinit.Thepackagestructureofthetestfoldershouldmimicthepackagestructureofthemainsourcefolder.Iusuallyspecifythattestclassescontainthenameoftheclassunder test(e.g.,CustomerDAOTest)andexist in thesamepackageas theclassundertest(soprotectedmethodscanbetestedaswell).

How often are unit tests expected to be run?Who fixes themwhen theybreak?Ideally,theseunittestsareruninsomeautomatedfashionatleastonceaday.Thetroublereallycomeswhenaunittestbreaks.Theconventionalthinkingis that the developer who checked in the code responsible for the breakageshouldfixit.However,inanactiveproject,it’snotalwaysobviouswhocheckedin the mistake that broke the unit test. For example, there might not be anoffending check-in; a developer could have changed the input data that theparticulartestrelieson.Also,inanactiveprojectwithloomingdeadlines,fixingthetestcasesoftengetslowerpriority.

Often,theapplicationarchitectadvisestheprojectmanageronthistopicbutdoesn’tunilaterallydecidetheanswer,asmanagingwhichtasksareassignedtowhichpeopleisreallytheprojectmanager’sresponsibility.

Oneoptionistorotatetheresponsibilityforfixingunittestbreakage.Thisisofteneasiertomanageastheprojectmanagercanexpectlessfromthatpersonwhentheyareonunittestpatrol.Italsopunishesdeveloperswhocheckincodethat breaks the unit tests by embarrassing them (e.g., calling attention to theirmistakes by calling the attention of others to them). Therefore, it provides anincentive for developers to not check in code that breaks unit tests.Unfortunately,italsoprovidesanincentivefordevelopersto“commentout”unittestssotheyaren’tembarrassed.

Whatenvironmentaremyunit tests expected torun in?Most applicationsrequireexternalresources,suchasdatabases.Usually,Imaintainadevelopmentdatabase thatservicesdevelopment tasksandunit testsandaseparatedatabasefor automated integration tests. Some organizations have developers maintaintheir own databases for development, but that’s an inefficient use of time.Developersbydefinitionaren’tdatabaseadministratorsandcan’tsolvedatabaseenvironmentissuesasquickly.It’smoreefficienttohaveonepersonwiththeseskillsmaintainthatenvironmentforeveryone.

Whatunittestingtoolsareinthetechnicalstackandareavailableforuse?Some additional tools are needed to support unit tests. The Junit testingframework (http://www.junit.org/) appears to be the most popular and is theframeworkmyprojectsuse.Inadditiontothetestingframework,it’snormaltoneed a mocking framework to provide implementations for interface classdependencies that aren’t the subject of a particular unit test. I typically useEasyMock(http://easymock.org/),butthereareothertoolsavailable.

It’s important that libraries and toolsneeded forunit testing aren’t usedbyproduction code. Toward that end, I usually define a dev-lib folder in myprojects;dev-libcontainsjarsthatareneededfordevelopmentandunittestsbutwon’t be included in the production deployment. The build process usuallyenforces that developers don’t accidentally code a reliance on EasyMock orsomeothertestingproductinproductioncode.

In addition to selecting and making unit testing tools available in yourprojects, it’s often necessary to provide a base testing framework to makecreating unit tests easy. For instance, I frequently have a base unit test thatperformsallHibernateconfigurationtasksandatestJNDIfactory.Thisway,alladeveloperneeds todotocreateanewJunit test isextendthebase testclass.Frequently, this base will provide common mocks as well, e.g.,HttpServletRequest,HttpServletResponse).

AutomatedTestingAs applications mature and gain complexity, automated testing becomespreventativemedicine.Withcomplexcodecomesthelikelihoodthatadeveloperwillfixoneproblemandinadvertentlycauseanother.Somewouldsaythatthisis a red flag indicating a need for code refactoring, as discussed in a laterchapter.Automated testing decreases the possibility that a fix to one problemcausesanotherproblemandthengoesunnoticeduntilafterproduction.

Automatedtestingisbetterbecauseit’sconsistentandeasiertorun.Itdoesn’tslack off at the end of a hard day, and it’s easily repeatable. As a result,automated regression testing forevensmallchanges in theapplication ismorecost-effective.I’veseenprojectsthatgosofarastoincorporatethetestsuiteinthe build script. If one of the regression tests fails, the build fails and thedevelopersareforcedtofixthebug.

Automatedtestingisascompleteasyouwantittobe.Ifyousubscribetotheviewthattestcasesshouldbecreatedastheapplicationisdeveloped,thenyoualsofeelthatdevelopersshouldinitiallycreatetestcases.Butthesetestcasesareusually not complete. If you adopt the recommendation that the first step infixing a bug is writing a test case that reproduces it, your regression test isenhancedasyoufindmorebugs.Over time,yougetarobustsetofregressionteststhatincreasestheprobabilityoffindingbugsbeforedeployment.

Automated testing isn’t free. Creating and maintaining tests consumesmanpower,soit’simportanttousethe80/20rule.Initially,codetestcasesforthe80percentoftheapplicationthatismostcomplexandmostpronetoerror.Youcanfillouttheremaining20percentovertime.Ifyoustoptocreateautomatedteststhatare100percentcomprehensive,you’llendupaddingmanyhourstothetimeline,totheextentthatthecostswilloutweighthebenefits.

UnitTestingBestPracticesKeep test cases and supporting classes in a separate folder, but in anidenticalpackagestructure.Althoughtestcasesaredevelopedinconjunctionwiththeapplication,theyarenottrulyapartofit.Typically,youhavenoneedtodeploythemtoanythingbutyourtestingenvironments.

I usually organize the package structure of my test cases and supportingclasses after the application package structure. Keeping a consistent packagestructurewillsavedeveloperstime.

Adopt anaming convention for test classes thatmakes themeasy to find.Thisisanothersuggestionthatcansavedeveloperstime.Forinstance,InameallofmytestclassesTestXxx,whereXxxisthenameoftheclassbeingtested.Forexample, class TestValueObject is the test class for ValueObject. I prefer tocombine all unit tests for the same class into one test class, but this is not atechnicalrequirementorsuggestion.

Make each test case self-sufficient and independent.A test case should notrelyonothertestcaseshavingtoexecutebeforeit.Ifyouwritethetestcasesso

thattestcase#1hastoberunbeforetestcase#2willwork,it’snotobvioustootherdeveloperswhattheprerequisitesare,shouldtheywanttouseatestcasefor unit testing and debugging. However, there may be some isolated caseswhereimplementingthissuggestionisn’tpractical.

INTEGRATIONTESTINGIntegration testing (sometimes known as acceptance testing) verifies that anindividual software feature or function works as intended. Typically, Iconsolidate the environments for integration testing and system integrationtestingas their requirementsaresimilarenough.Onecomponentof integrationtesting certainly can be Junit tests executing presentation layer support classmethodsthatsupportmajorfeaturesoftheapplication.Itisdifficult,however,tocompletely automate integration tests for GUI features. While testingframeworkscanverifythatafeatureworkswithoutexception,itcan’tverifythatthe GUI aesthetics are correct. For this reason, I usually maintain a manualregressiontestplanformyprojects.Atthisstage,developersshouldbemakinganyneededmodificationstothatregressiontestplansothatitaccommodatesthenewfeature(s)beingadded.

SYSTEMINTEGRATIONTESTINGSystemintegrationtestingisaprocessthatensuresthatthesoftwareproductasawholeworksasintended.ThisprocessisusuallyexecutedinpreparationfortheUserAcceptanceTestingperiod.During this phase, developers (or a subset oftest team members) execute the manual regression test. Developers areresponsibleforfixinganydefectsfound.

The responsibility of the application architect for this process is usually toensure that the environment supports this type of testing activity. Developerstypically need an easy way to initiate the build and deployment to thisenvironment. I find it helpful to standardize the build and deploymentprocedures across environments and projects. Not only does this streamlinemaintenanceforyourbuildanddeploymentscripts;italsomakeslifeeasierfordevelopers,who are often transferred between projects inmany organizations.This consistency allows developers to concentrate on the testing activity itselfandtherequireddefectfixes,ratherthanspendingunnecessarytimewithuniquebuildanddeploymentproceduresforaparticularproject.

USERACCEPTANCETESTINGUser acceptance testing usually requires a separate environment. This ensuressome stability for the testing team (or user side representatives in someorganizations).Usually,theapplicationarchitectoraseniordevelopermanagesneeded changes to this environment so that those changes can be made inproductionwhentheprojectiseventuallydeployedtoproduction.

Onceagain,theapplicationarchitect’srolewiththisprocessistoensurethatanenvironmentexiststosupportthisactivity.Usually,Imanagechangestothisenvironment so I can ensure that needed changes will also be made in theproduction environmentwhen the time comes. If changemanagement for thisenvironment is decentralized (i.e., changes managed by several people), thechance thataneededchange ismissedwhen theprojectdeploys toproductionincreasesdramatically.

Formyprojects,Iusuallyreviewdefectticketsandcheck-insduringtheUATtesting period. This provides feedback as to howwell I didwith design tasksearlierintheproject.Defectsatthisstageoftheprojectshouldnotrequiremajorarchitecturalchanges.Iftheydo,thisneedstobeanalyzedsothatthosekindsofmistakesarenotmadewithfutureprojects.

PERFORMANCETESTINGPerformance testing is a process that verifies if the project meets scalabilityrequirements in termsof thenumberofusersandtransactionsitsupports.Thisprocessrequiresdirectinvolvementoftheapplicationarchitectoraveryseniordeveloper. To be honest, I take it upon myself to participate in this exercise.Developersknowwhen theyscrewupwhenunit tests failordefectsappear intesting.Architectsneedsimilarfeedback.Performancetestingisagoodwaytofind out if the application architecture meets (or can be tuned to meet)performancespecifications.

Whenconstructingaperformancetestplan, thefollowingquestionsneedtobeanswered:

Whatmetricswillbemeasured?Whatmeasurementsarerequiredto“pass”theperformancetest?Whatproductsandtoolswillbeusedtoconductthetest?Whatfeatureswillbeincludedinperformancetests?

Theapplicationarchitectisresponsibleforensuringthatthesequestionsareansweredandoftenwillfacilitateneededdiscussionswithotherteammembersandend-userrepresentativestoanswerthesequestions.

Whileapplicationarchitectsoftendon’texecuteperformancetesting,theyareoften called on to contribute should problems be discovered. It is possible forperformancetestingtobemanagedbyseniordevelopersratherthanapplicationarchitects.However, Icloselymonitor thisprocess formyprojects,even if it’sperformedbydevelopers,asitisvaluablefeedbackonthequalityoftheinitialdesign.Howeasyordifficultitistotunetheapplicationreflectsdirectlyonthequalityoftheunderlyingapplicationarchitecture.Ifthereareindeeddifficultiesin tuningoneofmyapplicationsper requirements, Iwant tounderstand thosedifficultiessoIcanavoidthemwithotherapplications.

Whatmetricswillbemeasured?Measurementsmustbecompletelyobjective.I usually measure throughput (e.g., 20 hits per second) and average clientresponsetime(e.g.,threesecondsperhit).Mosttoolsthatsupportperformancetestingwillprovidethesemetrics.

YoumightwonderwhyIdon’tpayattentiontothe“numberofvirtualusers”and state the objective in terms of the maximum number of virtual users theapplicationcansupport.Afterall,mostenduserswouldrelatetothenumberofsupportedusersbetterthanthroughput.Thereasonisthatbycontrollingthelagtimebetweenhits(somethingthatmostloadtesttoolsallowyoutoconfigure),Icanmakeanysoftwareproductachievealmostanynumberofconcurrentusers.Byincreasingthelagtime,Icanachieveahighernumberofconcurrentusers(infact, any number required by the business).While this initially placates users,measuring the supported number of virtual users allows me to rig the test.Throughputcannotberiggedinthisway,whichiswhyIuseit.

Whatmeasurementsarerequiredto“pass”theperformancetest?Thisisanarbitrary decision and often discussedwith end-user representatives. I usuallyrecommend aiming to support twice the throughput needed to support theapplication in production. For example, if the production application typicallysupports 5 hits per second in production, I usually ensure that the applicationsupports10hitspersecondinperformancetests.Thisprovidesheadroomshouldanunexpectedusagesurgebeencounteredinproduction.

Although there are always opportunities for performance improvement,performance tuninghas diminishing returns over time.Whenyou start tuning,thechangesyoumakewillresultinlargerperformanceimprovements.Butover

time, your improvementswill get smaller and smallerwithmost applications.Becausemostofthebenefityougetfromtuningwilloccurinthefirst20percentofthework,the80/20ruleappliesonceagain.

Whatproductsandtoolswillbeusedtoconduct thetest? Iusually relyonAdmin4J (http://admin4j.net/) for server-side performance metrics and Jmeter(http://jmeter.apache.org/) to script and run the performance test itself. Jmeterwilloptionallyprovideclientresponsetimestatisticsandthroughputstatisticsaswell.

WhileAdmin4Jmight appear tobe redundant, it isnot.StatisticsAdmin4Jreports are server-side. That is, they don’t include web server, firewall, andnetworklatencytime.Jmeterstatisticsareclient-sideanddoincludetimetakenbythewebserver,firewall,andnetwork.Ifaperformanceorscalabilityproblemsurfaces, it’s important to be able to distinguish between problems with theapplicationandproblemswiththeenvironmentitrunsinasthetacticsyouusetosolvethoseproblemsaredifferent.

Whatfeatureswillbeincludedinperformancetests?Itisoftennotpossibleorevennecessarytoincludeeveryproductfeatureintheperformancetest.Thecontentoftheperformancetestisusuallytheresultofadiscussionwithend-userrepresentatives. I usually recommend scripting the most commonly usedfeatures. Typically, you can figure out what these features are from anexaminationoftheproductionaccesslogs.

I try to keep this feature set and the performance test script consistentbetweenreleasesasmuchaspossible.Thismakescomparisonsofperformancebetween releasesmoremeaningful. For example, if a common function testedoutat5hitspersecondinthelastrelease,butonlysupports3hitspersecondinthecurrentrelease,somethingchangedintheapplicationortheenvironmenttonegativelyimpactperformance.

Performancetestsarenotfunctionaltests.Manymanagersmakethismistake.Often, theperformance test scriptsarenotcomprehensiveenough to substituteforfunctionaltests.However,itisimportanttovalidatethateachrequestintheperformance test is workingwithout error;measuring the speed of your errorpage isn’t all that useful, even though it can produce some impressiveperformancenumbers.

I often monitor performance test runs personally to ensure that I capturemetricsneededforanalysisshouldperformancetestsfail.Often,ifperformanceisn’t meeting requirements, I’ll capture the following information during a

performancetest:

ThreaddumpO/SDiskusagemeasurementsO/SCPUusagemeasurementsO/SNetworkusagemeasurementsDatabasedisk,memory,andlockcontentionmeasurements

Threaddumpswill tellme if there is any Java-level synchronization issuesthat need to be addressed. The O/S measurements will tell me if resourceconstraints are an issue.Databasemeasurementswill often tellme if databasetuningisneeded.

PerformanceTestingTipsandGuidelinesDon’t start tuninguntil after theapplication is inuseracceptance testing.Manydevelopershaveadesiretotuneeverypieceofcodetheywrite.Iadmiretheirdesireforcompleteness,butithurtsthetimelineoftheproject.Chancesarehighthatagoodpercentageofthecodebeingtunedatthislevelwillnotresultingoodperformanceenhancementtotheapplicationasawhole.AlthoughI’vemetmany developers that are not comfortable with this concept, experience hastaughtmethatatsomeplacesintheapplication,thecostoftuningdoesn’treapenoughbenefitforanyonetocareaboutit.

Mostperformanceproblemsoriginate inapplicationcode.Developers tendtoferretoutperformanceproblemsbyexaminingcontainerconfigurations,JVMoptions, operating system performance, network performance, and the like,rather than looking at code. This is usually wishful thinking on the part ofdevelopers.

Measureperformancebeforetuningtoestablishabaseline.Thenextsectiondiscusses how to measure performance. The numbers that result fromperformance measuring will be the basis for judging the effectiveness ofperformance improvements. I also keep a log of changes I make to anapplicationbetweenperformance tests.Thisway Iknow if the tuningeffort ishelpingorhurtingandtowhatdegree.

Alwaysrunloadtestsunderthesameconditionsmultipletimes.Youneedtomakesurethatnothingisinterferingwiththetestthatyou’renotawareof.I’ve

seenloadtestsaccidentallycontendingforbatchrunsorserverbackups.Ifyouruneachtestatleasttwiceandgetsimilarresultseachtime,thenyou’llhaveahigherdegreeoftrustintheinformationJMetergivesyou.

Documentandlimitchangesbetweeneachtest.Ifyoumakeseveralchangesbetween load tests, you won’t know which of the changes helped or hurtperformance.Forexample, let’s sayyouchangedfour things. It’spossible thatoneof the changes helpedperformance, one of the changes hurt performance,andtwodidn’tmakeanymaterialdifferencewhatsoever.Becauseyoucombinedthe changes, however, you’ll never really knowwhat helped performance andwhathurtit.

MonitorandrecordCPUandmemoryusageduring the test.The simplestway todo this is at theoperating system level.MostUNIXoperating systemsprovideatoputility,whichprovidesCPUandmemoryusageforeachprocessaswell as usage for the entire server. You’re obviously interested in what’shappening for the container process during the load test. Listing 16.1 is anextractfromatoputilityoutput.IfyourapplicationrunsonaWindowsplatform,you’llneedtousetheperfmonutility.

Listing16.1:SampleTopUtilityOutput

It’s more convenient to limit top utility output to the process running thecontainer. Unfortunately, the options to the top utility are different for eachplatform. For instance, on Solaris, using the –U option will limit output to aspecificuser.top–Uusername

OnLinux,youwouldlimitoutputbyspecifyingtheprocessIDwiththe–p

option.top–ppid

Ifyou’reusingaUNIXotherthenLinux,you’llhavetoconsultthemanpageforthetoputilityforyourspecificUNIXplatform.Bytheway,Loukides(2002)isanexcellent referencefor interpretingCPUandmemoryutilizationstatisticsthatUNIXutilitiesprovide.

YouexpecttoseebothCPUandmemoryusageincreaseduringthetestanddecreaseafterthetest.Ifyoudon’tseememoryallocationdiminishafterthetest(e.g.,withinfifteen to thirtyminutes), it’s likely thatyouhaveamemory leak.YoushouldprofileyourloadtestbothforCPUusageandmemoryusage.

Asdiscussedpreviously,IusuallymonitorheapmemoryviaaJMXconsolesuch asVisualVMor Jconsole.Memory at an operating system level includesmemorythatisn’tdirectlycontrolledbyapplicationcode.

Useloadteststodetectmemoryleaksinadditiontoperformance.Yes,eventhoughJavahasagarbagecollectorformemory,it’sstillpossibletohavealeak.It’sfairlyeasytodetermineifyouhaveamemoryleak;it’smuchhardertofindwhereitis.Therewillbemoreonidentifyingmemoryleaksinthenextchapter.

MeasuringPerformanceunderLoadMostloadgenerators(suchasJmeter)operatebyrunningatestscript(orasetofthem) several times concurrently, simulating a configurable number of virtualusers.Bymeasuring theperformanceeachvirtualusergets, the loadgeneratorenables you to examine the performance averages over all virtual users.Sometimesthisinformationispresentedgraphically.

Asanexample,I’vewrittenaJmeterloadtestfortheAdmin4Jproduct.Theresultsoftheloadtestareinfigure16.1.Thetwomostimportantnumbersintheoutput are the 10.5 hits per second (hps) throughput rate and the average 29millisecond client response time. As you would expect, the throughputrequirements are quite low (e.g., 2 hps with a response time of less than 2seconds is reasonable) as these are pages accessed infrequently by supportdevelopersinvestigatingproblems;10.5hpsshouldbemorethanadequate.Thegeneralruleisthatusersdon’tliketowaitmorethantwosecondsforaresponse;the29msaverageresponsetimemeetsrequirements.

Figure16.1:SampleJMeterLoadTestExample

LoadtestsareusuallywrittenintheformofURLsequences.Iprefernottoset up tests for other classes unless the application has significant back-endprocessing that needs to be tested under load. This can happen if yourapplicationprocessesJMSmessagesfromotherapplications,forexample.

Althoughaloadgeneratorcantellyouifyou’remeetingperformancetargets,it can’t tell you why your performance is what it is. If you meet yourperformance targets, you should stop the tuning effort. If youdon’tmeetyourtargets,you’llneedtoapplyadditionaltechniquestodiagnosethecausesoftheperformanceproblem.

Shouldyouidentifyaperformanceproblemandneedtotuneanapplication,there’smaterialonimprovingperformanceinthenextchapter.

It shouldbenoted that thereareawidevarietyofbrowser-based tools thatcanbeusedtomeasureandimproveperformance(e.g.,PageSpeed,SpeedTracer,andYSlow).Measurementsyougetfromthesetoolsdo,however,includemuchmorethanapplicationperformance;theyalsoincludenetworkperformanceandperformance of the device running the browser. Two people measuringperformanceofthesamepageusingthesametestscriptfromdifferentpartsoftheworldondifferentcomputersmaygetdrasticallydifferentresults.

MemoryLeaksDefinedWithJava,memoryleaksoccurincodethatretainsreferencestoobjectsthatareno longerneeded.A reference is avariabledeclarationandassignment. Java’sgarbage collector periodically freesmemory associatedwith non-referenceable

variables.Ifavariableisreferenceable,itsmemorywillnotbefreed.For instance, thevariableaccount in thefollowingcodeisareferencefora

valueobject:AccountVOaccount=newAccountVO();

If this lineofcodeappearsasa localvariabledeclarationwithinamethod,thereferenceendswhenthemethodcompletes.Afterthemethodcompletes,thegarbagecollectorfreesmemoryassociatedwiththeaccountdeclaration.

If the declaration is an instance-level field, the reference ends when theenclosingobjectisnolongerreferenced.Forexample,ifthevariableaccountisdeclared as an instance-level field for CustomerVO, the reference to accountendswhen the reference toan instantiatedCustomerVOobjectends,asshownhere:publicclassCustomerVO

{

privateAccountVOaccount=newAccountVO();

}

A variable defined as static can easily cause a memory leak because thereferenceendswhentheJVMstopsorthereferenceisspecificallynulledout.

Memory leaks inJavaEEapplicationsare frequently causedby staticallydefined Collection objects. For instance, it’s common to statically define anapplicationPropertiesobjecttostoreconfigurationdetails,asinthefollowing:publicclassEnvironment

{

privatestaticProperties_configurationProps=newProperties();

}

Any value stored in this statically defined Properties object can bereferenced.Collectionobjects, such asProperties orHashMaps, often producememory leaks because it’s easy to put values into them and forget to removethemlater.

IdentifyingMemoryLeaksToidentifymemoryleaks,notehowmuchmemorythecontainerisusingbefore,during, andafter the test.You should seememoryat a low level to start, thenrampupduring the test, and slowlydecreasewithin a fewminutes to anhourafterthetest.Forexample,acontainermightinitiallystartat128MBofmemoryand grow to 180MB during the performance test. After the test, memoryallocationshould trendback toward128MB. Iusually run this test for twenty-fourhours(longenoughtorevealslowermemoryleaks).

Load testing will not find all memory leaks. Note that even if nomemoryleaksareidentifiedwithyourloadtestsuite,therestillmightbeamemoryleakintheapplication.Mostloadtestscriptsaren’tcomprehensive;thatis,theydon’texecuteallfeaturesofanapplication.Itispossiblethatthere’samemoryleakinyour application that isn’t a part of your load test suite.Most of the time, theamount of resources it takes to create and maintain comprehensive load testsuitesismuchmorethanmostorganizationsarewillingtofund.Becauseofthis,it’s important to instrument your applications and configure your Java EEcontainers so you get enough information should memory shortages occur inproduction.More information on how to accomplish thiswill be presented inchapter16.

Memory leaksaremost likelydiscovered inproduction.While I encourageyoutocheckformemoryleaksbyrunningaloadtestfortwenty-fourhoursormore, the load test will only execute what’s scripted. If the load test scriptdoesn’tcreatetheconditionsforthememoryleaktooccur,thenrunningtheloadtestforalongperiodoftimewillnotuncovertheleak.

I use VisualVM (http://visualvm.java.net/) to monitor memory duringperformance tests. VisualVM is a JMX console and requires that you open aJMXport for thecontainerbeing tested.Youcanalsouse Jconsoleutility thatcomeswiththeJDK.IpreferVisualVMasithasawiderselectionofpluginsandhasmanyotherusesinadditiontomeasuringmemory.Whileyoucanmeasurememory at the operating system level, you can separate heapmemory (wherememory leaks typically occur) from the various othermemory pools typicallyallocatedinaJVM.

It’s not realistic for memory to return to its pretest level, but most of thememoryallocatedduringthetestshouldbefreed.Toinvestigatememoryleaks,Istart takingamemorydumponce the leakhasbeenconfirmed.Whileyoucanusethejhatutilitytoreadthecontentofamemorydump,thisislaboriousand

time consuming. I usually use the commercial profiler YourKit to investigatememory leaks. The result of this should be that you’ve identified whichtransaction(s)aregeneratingtheleakandyoucanconstructaloadtestscriptorunittestthatwillproducethememoryleak.Givenareproducibleleak,youcanusetheprofilertoverifythefixafteryou’vefixedtheleak.

ConfiguretheJavaEEcontainertoproduceamemorydumpwhenthefirstOutOfMemoryError is thrown.This can be accomplished by specifying theXX:+HeapDumpOnOutOfMemoryErroroptiononthecontainerifyou’reusingtheOracleJVM.YoucanthenuseeitherthejhatutilitythatcomeswiththeJVMoracommercialprofiler to investigatewhere thememory isbeingallocated. IusethisconfigurationoptionforallJavaEEcontainersinallenvironments;andthis isn’t just for load testing. Should amemory leak occur in production, theinformationinthedumpwillbeveryvaluable.

Additionally,IuseAdmin4Jtogeneratealertsforabnormallyhighmemoryusage. These alerts come with a configurable amount of memory allocationhistory and a threaddump.The tool doesn’t automatically generate amemorydump as that is very resource intensive. The thread dump may be useful inidentifying transaction types that are potential targets for a memory tuningexercise.

InvestigatingPerformanceProblemsAt some point, a load testwill identify performance problems and issues thatneedtobesolved.Performancetuningfollowsthe80/20rule;youget80percentof the benefit from the first 20 percent of the work. After identifying theproblem,thenextinformationyouneediswhereinyourcodeyou’respendingthe most time. Profilers do this nicely. However, before even profiling theprocess,takeathreaddumpduringtheloadtestthatfailed.

Oneoutputofloadtestingisknowingwhichtransactionsarenotperformingto requirements. In the layered application architecture discussed in this book,the business layer and the data access layer are the most likely places forperformance problems to occur. Beans and web services usually only publishfunctionality in business objects anyway. It should be relatively quick toconstructatestcase(ormodifyanexistingone)specificallyfortheunderlyingbusinessobjects thatproduce theperformanceproblem.Constructing these testcasesgivesyousomethingthat’seasiertoprofile.

Takeathreaddumpduringaloadtest.Believeitornot,athreaddumptaken

duringafailingloadtestwillhavethesameinformationaswhataprofilergivesyou;it’sjustnotaseasytointerpret.Letmeexplainwhythat’satruestatement.

Aprofilerworksbytakingacopyofallthreadstackseverydefinedinterval(usually five milliseconds or ten milliseconds). When methodCustomerDAO.findCustomerByState()is encountered, metrics associated withthat method are tallied. The more time you spend inCustomerDAO.findCustomerByState(), the higher those tallies and the moreyourprofilerconsiders thatmethodahot spot.Ahotspot is a sectionof codethatappearsasalargernumberofobservationsthanothersectionsofcode.Thiscan be either because it’s executed more often or because it takes longer toexecute.

Whenyoutakeathreaddumponaloadtestwhereallthreadsareatarandomplaceinthetestscript,you’reeffectivelytakingmanyprofiler-typeobservationsat once. If CustomerDAO.findCustomerByState()shows up in most activethreads,it’sahotspotandmayyieldperformanceimprovementiftuned.

TherearetoolsliketheThreadDumpAnalyzer(http://java.net/projects/tda/)thatmakeinterpretingathreaddumpabiteasier.Icheckthreaddumpsforlockcontention(threadsmarkedasBLOCKEDandwaitingonaresource).Profilingonethreadwillnottellyouanythingaboutlockcontention.

Tuningmethods thataren’thotspots isn’tawiseuseof time.Forexample,say you can tune a section of code and get a 10 percent performanceimprovementonit.Tuningahotspotconsuming50percentofyourtimewillgetyoua5percentthroughputimprovementoverall(50percenttimes10percent).Tuning some other method that only consumes 5 percent of your time willgenerateonlya0.5percentthroughputimprovement(5percenttimes10percent)overall.

Useprofilertoolstotunehotspotswithaspecificunittestscript.Aprofilerreports the activity of a JVM at a configurable interval (typically every fivemilliseconds) and reports the call stack in use for every thread. Themethodstakingthemosttimewillmostlikelyshowupinmoreobservationsandprovideleadsastowhereyoushouldtune.MyfirstpreferenceistoconstructaJunittestthatexecutesthenonperformingcode.

IfyourcontainerusesoneJVM,youcanprofiletheentirecontainerandrunyourJMeter testscriptagainst it. IprofileaJavaEEcontainerasawholeasalastresortasprofilingindividualunittestsusuallytakelesstime.

SomeJavaEEcontainersusemultipleJVMs,makingitdifficulttoprofilethe

entire container. Instead, you’llwant to directly profile test cases that use theunderlying business objects. You’ll skip profiling the deployment andpresentationlayersintheirentirety,butperformancetuningismostlikelytobeat the business logic layer or lower anyway. In a layered architecture, thedeploymentandpresentationlayersdon’tperformmuchoftheprocessing.

Donotattempt toprofile inaclusteredenvironment.For thoseofyou inaclustered architecture, I recommend profiling in one instance only, not inclusteredmode.Yourgoalistotuneyourapplication,notwadethroughtheworkyourcontainerdoestoimplementclustering.

Profilerstellyouwhere(inwhichclassormethod)CPUtimeisbeingspentandwhere(inwhichclasses)memoryisbeingallocated.ThedefaultprofilerthatcomeswiththeJVM(HPROF)producesoutputthat’snotintuitiveandishardtoread, but that output contains much the same information as commercialprofilers.Theadvantageofcommercialprofilersisthattheymakeperformanceinformationeasiertoreadandinterpret.Ifyourorganizationhasalicenseforacommercialprofiler,useitinsteadofHPROF.

If you don’t have access to a commercial profiler, you’ll probably have tospend a few more minutes interpreting the output than your colleagues withcommercialprofilers.ThedefaultprofilermeasuresbothCPUtimeandmemoryallocation,butIrecommendmeasuringtheseseparatelytoavoidcontaminatingthe test. Methods for debugging memory leaks are also included in the nextchapter.

CHAPTER17

MAKINGJAVAEEAPPLICATIONSSUPPORTABLE

JavaEEapplicationsrequiresupporttovaryingdegreesjustlikeothertypesofapplications. In previous chapters, we’ve discussed at length error handlingstrategies, logging strategies, unit testing strategies, and other techniques toimprove the quality of your Java EE applications and make them easier tosupport. Those techniques are a beginning to making Java EE applicationssupportable, but they are not comprehensive. To start, exception logs andnotifications,while important,aren’tacompletesourceof informationwhen itcomes to diagnosing many types of outages, such as memory shortages orlocking issues. Furthermore, administrators also need to assist with capacityplanning efforts and helpmanagement effectively direct resources to improvequalityandaffectbugfixes.Thischapterwilldetail typicalsupport issues thatarisewithJavaEEapplicationsandsuggestwaystoinstrumentyourapplicationstoaddressthoseissues.

While application architects inmany organizations aren’t directly involvedwithprovidingapplicationsupport,theyshouldbeconcernedwiththeresourcesrequired tosupport theapplications theydesign.Havingarchitects’ support forthe applications they design is extremely constructive as it provides valuablefeedbackthattheycanuseonfuturedesigns.

APPLICATIONSUPPORTOBJECTIVESMost organizations seek to maximize the end-user experience with theirapplications while minimizing the costs associated with providing thatexperience.JavaEEapplicationsarenodifferentthanapplicationsbuiltonothertechnicalstacks.

Thesetwoobjectivesareextremesinthesamecontinuum.Thatis,providingbetterend-userexperiencesoftencostsmoreintermsoflaborcosts.Conversely,cutting labor costs often lowers the end-user experience as it takes longer to

address problems and defects. Most organizations strike a subjective balancebetweenthesetwoextremes.

Maximizing theend-userexperiencewithanapplicationmeansminimizingunplannedoutages,minimizingdefects,providingacceptableperformance,andresolvinguser issueswith the applicationquickly and efficiently, amongotherthings.

Minimizing costs associated with providing a desired end-user experiencemeans minimizing the costs and time associated with addressing outages anddefects.Yes,partof thiscost is thevarious testingproceduresandframeworkssupportingtheapplicationasthesepreventdefectsinthefirstplace.However,nomatterhowrobustyourtestingproceduresandframeworks,defectswillsurfacein production. Minimizing costs for defects at this point means minimizinginvestigationtimeandthetimeinvolvedindiagnosing,fixing,andtestingthefixfortheissue.

STREAMLININGINVESTIGATIONSFORAPPLICATIONDEFECTSDefectsarereportedbyusersandinmanycasesbytheapplicationitselfthroughgeneratingexceptions.Ifloggingandnotificationsareputinplace,it’spossibleforapplicationsupportpersonnel tobealerted toasystem-generatedexceptionbefore it is reportedbyendusers.Furthermore,notalldefectsare reportedbyendusers.Therearemanyreasonsforthis:ittakestimetheymaynothave,theymayincorrectlyassumesomebodyelsehasreportedthedefect,oritmaybethatthe response timeon reporteddefects is less thandesired so theydon’t botherreportingthem.Thepointisthatsomedefectswillonlybereportedviasystemexception.

User-reported defects can be accompaniedby system-generated exceptions.While system-generated exceptions are more detailed and can provide morereliable information to developers, it’s not always easy to infer from anexceptionexactlyhowtheuserisbeingaffected.It’simportanttonotethatnotallapplicationdefectswillproduceanexception.Havingtheabilitytoincreasethelogginglevel(e.g.,todebug)inproductionatruntimeisvaluable.

Prioritize defects using the number of system-generated exceptionsproducedbythatdefect.Thenumberofexceptionsisusuallyagoodindicatorofhowoftenusersareexperiencingthedefect.Byprioritizingdefectsproducing

thelargernumberofsystem-generatedexceptions,youhelpthemostpeoplethesoonest.Admin4Jcanhelpyousummarizeloggedexceptionsandletyouknowwhichexceptiontype/defectishappeningmostoften.

Prioritizedefectsindicatingthelackofneededresourcesfirst.Anexampleofthisisdatabaseunavailability.Resourceoutages,suchasdatabaseunavailability,usuallyaffectalargenumberoftransactiontypesanduseractivitieswithintheapplication.

System-generated exceptions usually precede corresponding user-reporteddefects.Consequently,ifasystem-generatedexceptionisfixedquicklyenough,it’spossiblethatauserwillnevernoticeorreportit.Igenerallymonitorsystem-generated exceptions closely after a new release. This gives me an earlyindication ifwe’ve accidentally released a newbug and givesme a chance tostartaddressingtheissueevenbeforeit’sreportedbyusers.

Followbestpractices forgeneratingexceptions. Ideally,enough informationshouldbe present in the exception report to diagnose the bug and formulate astrategyforarepair.UseContextedExceptionandContextedRuntimeExceptiontosafelyincludeusefulinformationwithyourexceptions.Thereasonforthisistosavedevelopertimeininvestigatingthedefect.Iftheexceptionreportdoesn’tprovideenoughinformationtodiagnosethebug,thenyouhavetwochangestomake: correct the bug and enhance the error report to save developers timeinvestigatingfuturedefectreports.

STREAMLININGINVESTIGATIONSFORUNPLANNEDOUTAGESCommoncausesforunplannedoutagesinJavaEEapplicationsincludememoryshortages,javalockingorraceconditionissues,orunexpectedheavyuserload.For these types of outages, the time it takes to investigate is typically greaterthanwhat’s required to actually fix them.This sectionwill showyouways toinstrumentJavaEEapplicationstohelpreducetheinvestigationtimeassociatedwiththeseevents.

Additionally,low-levelbugswiththeJavaVirtualMachine(JVM)cancauseJavaEEcontainercrashes; thankfully, crashesdue to JVMbugsare rare thesedays.

InvestigatingMemoryShortages

Heapmemoryshortagescomeintwocategories:leaksandusagespikes.Leakstypicallycomefrommemorythatisaccidentallyreferencedlongerthanneeded.Memory that is referenced cannot be garbage collected and occupiesmemorythatcouldbebetterusedfornormalapplicationactivities.Whenleaksarelargeenough, there’s no longer enough memory to service user requests and thecontainer becomes inoperative. Usage spikes arememory used to satisfy useractivities.Usagespikescanbe initiatedbyunexpectedlyheavyuservolumeorunexpectedlylargeuserrequestsforinformation.PleasenotethatJavaallocatesmemory forpurposesother than theheap,butnon-heapshortagesare rareandarenotedbyveryspecificexceptions;plustheyareeasytosolve.Consequently,thissectionconcentratesonheapmemoryissues,whicharethemostcommonbyfarandthemostdifficulttosolve.

The first and most important question with any memory shortageinvestigation: Is it a memory leak or a usage spike? The answer to thisquestionisimportantasitdictatesactivitiesfortherestoftheinvestigationandyour options for fixing the issue. Memory leaks, once identified, are usuallyaddressedwithacodefixifyoucontrolthecodecausingtheleak.Usagespikescanoftenbereducedbytuningmemoryconsumptionandfindingwaystosatisfyuser needs using less memory. Usage spikes can sometimes be addressed byplacing limitsonuser capabilitieswithinanapplication.Forexample, limitingtheamountofinformationthatcanberetrievedfordisplaycanoftenreducethesizeofusagespikes.Anexampleofthiswouldbewritinganapplicationsothatif a user initiates a search that returns a large result set, the first five hundredrows(orwhateversizeischosen)wouldbeprovided,alongwithausermessageinforming them thatmore resultsareavailable, if required.Once theseoptionsareexhausted,youcanallocateadditionalmemorytotheJVMtoaccommodatetheload.

Often,memoryshortageproblemsaredifficulttoinvestigateastheremaybelittleinformationastowhatmemorywasallocatedatthetimeofthecrash.Thatis,ifinvestigatorshappenedtobeonhandduringarun-uptoamemoryshortageand somehow knew about the impending crash, they could initiate amemorydump and thread dump of the container, identifymemory allocations that areunexpectedlylarge,andalsoidentifyalistofuseractivitiesinprocessatthetimeofthecrash.Unfortunately,imminentmemoryshortagesarealmostneverknowntosupportpersonnelinadvance.ForthoseusingtheOracle(formerlySun)JVM,memorydumpsaretakenwiththejmaputility.Threaddumpscanbetakenwith

thejstackutilityorprogrammaticallywithinthecontainer.There are a large number of monitoring tools that alert administrators to

memory shortages. Open source examples of such tools include Zabbix andNagios. In addition, there are a plethora of commercial alternatives available.These tools are often implemented and configured at an enterprise level, andmost of them can be configured to initiate a thread and memory dump inadditiontoalertingadministrators.Notethat takingmemorydumpsisresourceintensive,sotriggerautomaticmemorydumpswithcare.Mostofthesetoolsrelyon the Java Management Extensions (JMX) and monitor from outside thecontainer. For those developers supporting applications for organizations thathave not implemented enterprisemonitoring tools,Admin4J providesmemorymonitoring services fromwithin the container and can be deployedwith yourapplication.

Memorycanbemeasuredatthecontainer-levelonly.Fororganizations thatdeploy multiple applications per Java EE container, identifying the offendingapplication within a container is much more difficult, as you can’t reliablymeasurememoryallocated to individualapplicationswithin thatcontainer.Forthis reason and others, I recommend deploying one application per container.Yes,thispracticedoesconsumeadditionalmemoryaseachcontainerhassomeamountofoverhead.However,onmostplatforms,memoryischeapthesedays.

Memoryleakscanbedetectedfrommemorydumps,butitrequiresdetailedknowledge of application code runningwithin the container.Without suchknowledgeof themonitoredapplications, theperson investigating thememoryincidentwon’t be able to tellwhat’s normal and expected allocation from thememory referencedby accident. If threaddumps takenduring the incident arealsoavailableandshownoactiveuserrequests,thenmemoryallocatediseitherfroma leakor is yet to be garbage collected.Memorydumpswill distinguishbetween referenced and non-referenced (available to be garbage collected)memory.

Memoryleakscanalsobedetectedbyanalyzingmemoryallocationpatternsovertime.Minimummemoryallocation(memoryconsumedimmediatelyaftergarbagecollection)foranapplicationwithmemoryleakswillalwaysgrowandnever shrink. For example, if a leaking application’s minimum memoryallocation one day is 100MB and thatminimum perpetually grows and nevershrinks,thenanapplicationwithinthatcontainerleaks.

Java lockingorracecondition issues cancausememory shortages.This isbecause locking issues keep user activities active for longer than they wouldotherwisebe.Whilethoseactivitiesareactive,memoryallocatedtoservicethemcannot be garbage collected and reused. In this case, thememory shortage isderivative.Thatis,it’snottherootproblemasitwouldn’texistifitweren’tfortheJavalockingissuesthatcausedit.Inthesecases,solvetheJavalockingissuefirst; thememoryshortage issuewilloftendisappearwhenthe locking issue issolved.Asanexample,JDBCdriverssynchronizetheabilitytocreatedatabaseconnections. That is, only one database connection can be created by thecontainerata time.Normally,withaproperlyconfiguredconnectionpool, thisisn’taproblem.However,shouldtherebeunexpectedlylargeuserdemand,thecontainermayhaveanunusually largenumberof threadswaiting fordatabaseconnectionstoworkwith.Aseachoftheseactivethreadsconsumememory,thiscanleadtoamemoryshortage.

It is possible for a Java EE container to be unstable after anOutOfMemoryException.Ontheotherhand,it’salsopossibleforthecontainertooperatenormallyandcompletelyrecover.Itdependsonexactlywhatthread(s)wereimpactedbythememoryshortage.It’spossiblethatathreadworkingwithmemorytrackingsessions,databaseconnections,orsomeotherneededresourcewasimpacted,leavingthattrackingmemoryinacorruptedstate.Otherthreadsattempting touse thatmemorymayencounterunexpectedconditionsanderrorout.For this reason, Iusuallyscheduleacontainer recycle for thenextnormalmaintenancewindow.

Resourcelimitscancausememoryshortages.Acommonexampleofsuchanevent is a database connection pool with a connection limit that’s too small.Manycontainerswillholdincominguserrequestsfordatabaseconnectionsuntilaconnectionisavailabletoservicetherequest.Ifyouhaveanunplannedlargenumber of requests, each request “held” for lack of an available databaseconnection consumes memory. I’ve seen this issue manifest as a memoryshortageissuemanyatime.Inthesecases,athreaddumptakenduringorshortlybeforetheeventrevealsthisissueratherquickly.

Iconcentrateoninvestigatingmemoryissuesratherthanfixingthem,astheinvestigation iswhat usually consumes themost time and resources.Once therootcauseofthememoryissueisfound,whetheritbethesourceofaleakoraspikeduetoaspecificuseractivity,fixingtheissueisoftencomparativelyeasy.Memory leaks usually require a code change. They usually involve statically

defined collections that are added to but never purged. Memory spikes canbecomethefocusofamemorytuningeffort.Oncetheactivityproducingaspikehasbeen tuned, theonlyalternative left isallocatingadditionalmemory to thecontainer.Theactivityoffixingmemoryissuesusuallyfallstoseniordevelopersrather thanthearchitect,butIfindmemoryinvestigationsandtheirresolutionsinformativeforarchitects.Shouldthecauseofamemoryissuebeadesignissue,knowledge of that defect can be used to avoid similar defects in futureapplications.

InvestigatingJavaContentionIssuesCode that uses the synchronized keyword is potentially a creator ofcontentionissues.Thatisbecauseuseofthesynchronizedkeywordforcesthatsectionofcodetobeexecutedbyoneandonlyonethreadatatime.Therearecaseswheresynchronizationisnecessary;however,itshouldbeusedwithcare.Thesynchronizedkeywordcanbedeclaredon individualmethodsor itcanbeused to guard access to all synchronized methods in a specific object. Entirebooks have been written on the subject of multi-threaded programming. Thattopicisreallyoutofscopeforthisbook.

Contention issues often appear to users as performance issues. Thebottlenecks that occur as a result of contention issues increase clock timeconsumed by all threads involved. Hence, contention limits throughput. Loadtests revealing contention issues will often display a throughput limit as asymptom.Asanexample,acontentionissueinoneofmyJavaEEapplicationslimitedthroughputofaloadtesttojustunder5hitspersecond(hps).Nomatterhowwechangedsettingson the load test,wecouldn’t exceed5hps.A threaddumpduringthetestrevealedthecontentionissue,whichwewereabletotunearoundandraiseourresultingthroughput.

Contention does not consumeCPU resources. That is, CPU utilizationwilloftenshowasignificantCPUpercent idle.Duringtheloadtestexamplein theprevious paragraph, therewere significantCPU resources availablewhen loadtestingmy applicationswith the 5 hps throughput limit.ThoseCPU resourcesdecreasedwhenthecontentionissuewasremoved.

Contention issues must be caught red-handed with a thread dump to bediagnosedandresolved.ThreaddumpsindicatewhichthreadsareBLOCKED(waitingonexclusiveuseofanobjectormethod)andwhichresourcethatthread

is waiting on. For more detail on thread states like BLOCKED, see Javadocumentation on the subject here. As with memory issues, having anadministratoronhandtotakeathreaddumpatthetimeoftheeventisoftennotpossible.Itisfarbettertoinstallamonitoringtooltodetectsuchconditionsandtakeathreaddumpautomatically.

MonitorJavacontentionandautomaticallytakethreaddumpsinresponseto contention events. This provides administratorswith real-time informationwhen contention events are encountered. I don’t see this feature natively inNagios or Zabbix, but both products are extensible enough that I’m sure it’spossible.Admin4Jwillmonitor threadcontentionand include threaddumps inthenotification.

Database connectionpools area commoncause for contention issueswithJava EE applications. This is primarily due to synchronization that occurswhencreatingdatabaseconnections.Contention involvingdatabaseconnectionpoolsislessofanissuewithJDK1.6andlater,butitstillcancauseproblems.Often, tuning the connection pool (e.g., themaximum number of connectionsandthenumberofallowedidleconnections)canalleviatecontentionissuesduetoconnectionpooling.

InvestigatingPerformanceIssuesMeasureperformance for allHTTP traffic, batch jobs, and JMSmessagehandling in production. Knowing current performance runtimes often isn’tenough;youneedsomeamountofhistorytounderstandifperformanceisslowerthan normal. It’s important to measure server-side performance of theapplication. I realize that users experience client-side performance, and that ismore important to them. However, poor client-side performance could be theresult of poor network performance instead of poor application performance.Measuringperformanceontheserversideistheonlywaytodistinguishbetweenthe two.Howyou improvenetworkperformance is fardifferent thanhowyouimproveapplicationperformance.

I’ve successfully used both the JAMon API and Admin4J for measuringserver-sideperformance.Bothproductsrunfromwithinthecontainer,andbothproducts are fast enough to use in production. Typically, HTTP trafficmonitoringisachievedthroughaservletfilter,andbothproductsprovidesuchafilteroutofthebox.

Establish performance targets for common application features.Performance tuning is an activity that doesn’t have to end. Furthermore, alltuningeffortshavediminishingreturnsovertime.Tuningonlyactivitiesthatarenotmeetingperformancetargetsisagoodwaytomaketheresourcesdevotedtotuningcosteffective.

Performancetuningbenefitsfollowthe80/20rule.Thatis,thefirst20percentof a performance tuning effort provides 80 percent of the benefit. As aperformance tuning effort progresses, incremental performance improvementsget smaller and smaller. For example, at the beginning of a tuning effort,identifying tuning opportunities that increase throughput 5 percent ormore iscommon. At the end of such an effort, identifying opportunities that increasethroughputmorethan1percentcanbeachallenge.

PerformancetuningactivitiesshouldbeplannedfortheUATtestingphaseof theproject.Acommonmistakedevelopersmake is toperformance tuneasthey develop. Tuning during development often results in tuning code that isinsignificantordoesn’trepresentalargeenoughtargettoprovidecost-effectivebenefittotheperformancetuningexercise.

Threaddumps takenathigh loadcanbeused to identifyhot spotswithinyour application. Hot spots are sections of code that are executed mostfrequently. Consequently, tuning hot spots often provides more benefit thantuningcodeexecutedlessoften.

Forthosewhomaynotimmediatelyseehowthreaddumpshelpidentifyhotspots,considerhowaprofilerworks.Aprofilerworksbytakingathreaddumpat a regular interval (say every 5 milliseconds) and recording whatclasses/methodsarecurrentlybeingcalledwithinthatdump.IfFoo.doWork()isexecuting in an active thread in one of these intervals, the time allocated toFoo.doWork() is incremented and the percentage of time spent inFoo.doWork()iscomputedfromthatallocatedtime.ThemoreintervalsinwhichFoo.doWork()appears, the higher percentage your profiler assigns it and themoreitappearstobeahotspotyourprofileridentifiesasatuningopportunity.Thesameconceptcanbeappliedtotakingathreaddumpinproductionathighload.ThemorethreadsinwhichFoo.doWork()appears,thehigherpercentageoftime spent in that method and themore benefit will be realized by tuning it.Thread dumps taken at high load will not replace your profiler, but they canoftenidentifyperformancetuningactivitiesworthpursuing.

Measureresourceutilizationonallapplication,database,andwebserversinproduction.MeasureCPUandmemoryutilizationaswellasI/Othroughputrates. Performance issues will often show up as a resource shortage. It isimportant to keep some amount of history as developers are often notified ofperformanceissuesafterthey’veoccurred.

DeployoneapplicationperJavaEEcontainer.It’smucheasiertoinvestigateunplannedoutagesastheamountofapplicationcodethatcouldhavecausedtheoutageissmaller.

TakeathreadandmemorydumpasstandardprocedurebeforerecyclinganinoperativeJavaEEcontainer.Itmayprovidesomeclueastowhatmadethecontainerinoperative.

ASSESSINGAPPLICATIONQUALITYI’lldiscusssomemetrics thatareused tomeasureapplicationcodequality.Astherearelimitationstoeachofthesemetrics, it isadvisabletoevaluateseveralmetricsinmakinganoverallassessmentofquality.

The number of application defects that made it into production is oftenviewedasanindicatorofapplicationquality.Thefewernumberofdefects,thehigher the perceived quality. The trouble with this measurement is that moreheavily used applications tend to havemore reported defects than rarely usedapplications.Thisissuecanbemitigatedbyscalingthenumberofdefectswiththenumberoftransactionsorpageloadsperunittimefortheapplication.

Thequantityofresourcesneededtoaddressuserissuesandcomplaintswiththeapplicationcanbeviewedasanindicatorofapplicationquality.Usually,thisismeasured in termsof the number of full-timedevelopers that are needed tosupport the application. This is often called Full-time Equivalents (FTEs).Applicationsarenotofthesamesizeorcomplexity;thefactthatoneapplicationconsumestwiceasmanyFTEsforsupportasanotherapplicationmightbedueto the size and breadth of features provided by that application. Hence, toeffectively compare the quantity of support FTEs for one application withanother,youmustweight theFTEsby some independentmetric (e.g., linesofcode,codelength,cyclomaticcomplexity).

Automatedtestcoveragecanbetakenasoneindicatorofquality.Thehigherthecoverage,thelessriskofunintendedconsequenceswhenthatapplicationischanged. We have already discussed the fact that few applications have 100

percent coverage and that higher levels of automated test coverage havediminishingreturns.Iusuallylookforatestcoveragepercentageofatleast60percent.

Simpler code is perceived as higher quality code, andmany tools exist tomeasurecodecomplexity(e.g.,JavaNCSS).Verycomplexcodetendstobemoredifficulttochangewithoutexperiencingunintendedconsequences.

IDENTIFYINGREFACTORINGOPPORTUNITIESRefactoring is rewriting selected code to make it easier to understand andmaintain.Fowler(2000)providesanextensivelistofconditionsthatindicatetheneedtorefactor—conditionshecalls“BadSmellsinCode.”Althoughhislistisso comprehensive Iwouldn’t presume to add to it, it is very code centric.ForreaderswhomaynothavetheintimateunderstandingofcoderequiredtoapplyFowler’sadvice,Idescribesomeobservablesymptomsthatmayindicateaneedtorefactorbutdon’trequireafullauditoftheapplication’ssource.

Classes that you can’t change without inadvertently creating other bugsmayneedtoberefactored.ThissymptomisreminiscentofthemovieNightofthe Living Dead. Some programming bugs don’t die; they just come back indifferent forms. Various circumstances can cause a bug to undergo such ametamorphosis.

Sometimes this happens when code within a class behaves differently,dependingoncontext.Forexample,Ihadoneclient thatusedacentralAPItoprovide reports for multiple applications. For political reasons, the APIinterpreted some of the argument values differently, depending on whichapplication was calling it (not a good idea, I know). Eventually, this serviceneeded to be refactored because we couldn’t change it without inadvertentlycausingbugsinsomeoftheapplicationscallingit.

Sometimesbugsmorphwhencodewithina singleclass isdoing toomuchand should be separated intomultiple classes. For example, one application Iworkedonhadtobeabletoacceptdatafrommultipledatasources.Someofthedatasourceswererelationaldatabasesandsomeweren’t.At first,wehadonlytwodatasources.Theprogrammer tookashortcutandputconditional logic intheclassmanaginginputtohandleeitherdatasource.Whenwehadtoadddatasources,theclasshadtoberefactored.

Enhancements orbug fixes requiring identical changes inmultiple classes

mayindicateaneedtorefactor.Somedevelopersarealmosttoofondofcopy-and-paste technology. Inmost cases, identical code inmultiple classes shouldbecomecommoncode“called”bymultipleclasses.Givenatighttimeframe,thedeveloperwhodiscoversacaseofcopiedcodemightnothavethetimetomakethe code common. The architect or manager can assist by providing amechanismtotrackthesecasessotheycanbefixedwhentimepermits.

Abnormallycomplicatedmethodsorclasses thatdevelopers fearchangingmay need to be refactored. Sometimes this symptom occurs in combinationwith themorphing-bug symptomdescribed earlier. It is another indication thatthecodeistoocomplexandneedstoberefactored.Ofcourse,thevalidityofthissymptomdependsontheassumptionthatdevelopersarerationalandtheir“fear”justified,whichmightnotalwaysbethecase.

CHAPTER18

FINDINGYOURWAYWHENTECHNOLOGIESCHANGE

OneofthechallengesofbeinganapplicationarchitectintheJavaEEspaceiskeepingupwiththesheernumberofthird-partyframeworks,tools,andlibrariesavailable,andthespeedatwhichtheychange.Becauseofthis,publishedworksoncomputertechnologytopicsbecomeout-of-datesoonaftertheyarepublished.Many of the best practices and advice presented in this book, and any otherpublished work, rely on features and toolsets available in the Java EE spacetoday. As technologies advance, the practices and advice presented in anypublished work in the computer technology space will at some point needrevisionandupdating.

It’stimetotaketheconversationupalevelandlookathowthatadviceandlist of best practices were derived; best practices and good advice are notarbitrarilycreated.

Applicationarchitecture,includingthebestpracticesandadvicepresentedinthis book, is guided by an underlying set of fundamental principles. Theseprinciples canbeused tohelpyoumake architecture anddesigndecisionsnotonly now but also down the road, as new frameworks, tools, and librariesbecome available and existing technologies advance. I’m not the first by anymeans to attempt to document application architecture principles. I also don’tclaim thatmy list ofprinciples is comprehensive; I havepurposefully reducedthesetofprinciplestothosethatarethemostimportantandthemostcommonlyused.

A principle is a primary law or truth that can be used to derive otherprinciples. Numerous examples of principles can be found in the worlds ofphysics and mathematics. Every young math student learns about thecommutative properties for addition inmathematics; namely that 2 + 3 is thesameas3+2.Thatpropertyisusedabundantlyinmathematicstoprovemorecomplex theories.Applicationarchitectureoperates ina similar fashion in that

it’sguidedbyabasesetoffundamentalprinciplesthatareusedtoderivemanyacceptedbestpracticescommontoday.OneexampleofafrequentlyreferencedsoftwaredevelopmentprincipleisDRYorDon’tRepeatYourself.

Idistinguishbetweenarchitecturalprinciplesandbestpracticesbecause thetwo are often confused. Best practices are principles applied to a specifictechnology,product,ordevelopmentcondition.Forexample,thebestpracticeofdesigningrelationaldatabasesusing3rdnormalformappliestheDRYprincipleand avoids recording the same data in multiple places. The best practice ofwriting unit tests along with your production code applies the principle thatcatching errors earlier is better than catching them later. The best practice ofchecking arguments for all public and protectedmethods applies the principlethatcatchingerrorsearlierisbetterthancatchingthemlater.Inessence,the“bestpractice”isaruleofthumbwrittenintermsthatcanbedirectlyappliedtoasetof specific situations and technologies. By contrast, the “principle” is theunderlyingtruththatmakesbestpracticesusefulandbeneficialtofollow.

Architecturalprinciplesworthdiscussinghaveseveralqualitiesorattributes.Architectureprinciplesareproductgeneric;thatis,theydonotreferencespecificproducts,frameworksortechnologies.Asillustratedabove,principlesareoftencombined with specific frameworks and products to form best practices.Architectureprinciplesaresimple;complexprincipleswillneverberememberedorapplied.Architectureprinciplesareapplicable; that is, theyareworded inaway that can be easily applied to new situations. Architecture principles areindependent; that is, they are unrelated to other principles. Architectureprinciplesarelogicallyconsistent;theydon’tcontradictotherprinciples.

Withoutfurtherado,architecturalprinciplesIfolloware:

Simplerisbetter.Reuse,don’treinvent.Enforceseparationofconcerns.Swimwiththestream.Catcherrorsearlierratherthanlater.Functionalrequirementsarethehighestpriority.

Notethattheseprinciplesareapplicableforallapplications,notjustJavaEEapplications.

SIMPLERISBETTERSimpler solutionsarealwaysbetter thancomplex solutions.This applies toapplicationcode,itappliestobusinessprocessesservicedbytheapplication,andit applies to IT support procedures needed to keep the application functioningproperly. Simpler solutions in application code are easier to understand andmaintain.Theyhavefewerdefects.Theyareeasiertoteachtonewmembersoftheteamandarequickerfornewmemberstolearn.Simplerapplicationsupportprocedures greatly increase the chance that they will be understood andfollowed, and it’s easier to bring new support developers on to the team.Furthermore, thesimpler theapplication is forusers, the fewerquestionsuserswillhaveregardinghowtoaccomplishtheirwork.

Tolerate only enough complexity to satisfy known business requirements.Some problems are naturally complex. For example, air traffic control (e.g.,keeping track of the position of all airplanes with the intent of avoidingcollisions) is a naturally complex business problem. Consequently, somecomplexity will be necessary in all applications. But we distinguish betweencomplexity that is required by the business problem and complexity that isunnecessary. Examples of unnecessary complexity are components that areintroducedbydevelopermistakeorpoordesigndecisions.Complexityrequiredbythebusinessproblemcan’tbeavoided.

Sometimesit’snoteasytodistinguishbetweenthetwotypesofcomplexity.Sometimes,a littleaddedcomplexitywillmakeplanned futurechangeseasier.Theproblemis that if thoseplansarechanged, then thecomplexitypreviouslyaddedbecomesunnecessary,andpotentiallyhardertomaintainwhileprovidingnobenefit.Forexample,weoftenmakeachoicewhether tohardcodeavalue,makeaneededvalueaconstant,ormakethevalueconfigurable(i.e.,passasanargumentorobtainthevaluefromtheenvironment).Theadditionalcomplexityneededtomakethehardcodedvalueadescriptivelynamedconstantislow,anditdoesn’taddtothenumberofneededtestcasesasthere’snoconditionallogicinvolved. It communicates to future developers what the value describes andvery possibly saves developers time inmaking changes down the road.Mostdevelopers would be comfortable with the small amount of additionalcomplexityneededtosupporttheconstantasopposedtothehardcodedvalue.

It’softentemptingtomakethatvalueconfigurableandmakethatsectionofcodemoreflexible,andperhapsmoreeasilyusable,inotherusecases.However,makingthatdecisionaddsconditionallogic(i.e.,youneedtotesttheconfigured

valueandproduceadescriptiveerrormessageifthevalueisinvalid).Usingthe“simplerisbetter”principle,makingthevalueconfigurableshouldnotbedoneuntilit’sneededsinceitaddsconditionallogic.Applyingthe“simplerisbetter”principletodecidingwhethertohardcodethevalueormakeitaconstantismoredifficult.Strictlyspeaking,makingthevalueaconstantisn’trequiredtoproduceworkingsoftware.However,makingcodeeasytoread(andconsequentlyeasiertochange)isanimplicitbusinessrequirementthatwelivewithmostofthetime.Mostofuswouldgoaheadanddeclaretheconstantforcodereadabilityreasons.

Consistency isa formof simplicity.This canapply to codingconventions aswellasproductchoices.Consistencyincodingconventionsoptimizesdevelopertime and reduces the amount of needed documentation. For example, if yourpackagestructureisconsistentinallyourapplications(e.g.,dataaccessobjectsinthe.dao.package,userinterfacerelatedclassesinthe.ui.package,etc.),thenit’smuch easier for newdevelopers to find code they seek, even if they havelimited experience in aparticular application.Analternativepackage structuremayhave small incremental improvements, but thosedifferenceswill cause atleast some amount of confusion among developers. This confusion will slowthem down. Granted, a different package structure may not slow down adeveloperall thatmuchforall that long,butotherexamplesofdifferencesaremoreinvasive.

Asanexampleofconsistencywithproductchoices,consideruser interface(UI) frameworks.Most UI frameworks are complex and require a significantlearningcurve.ConsiderStruts,StrutsII,JavaServerFaces,oranyoftheotheruser interface frameworks. Standardizing on one UI framework (i.e., beingconsistentwithyourproductchoice)throughouttheenterpriseallowsdeveloperstomoreeasilytransitionbetweenapplications.Thesameconceptcanbeappliedtopersistenceframeworksandotherincludedproducts.

Standardize solutions to common problems across the enterprise. Forexample, ifsomeapplicationsneedtoprogrammaticallytransferdatafromonehost to another, adopting a common librarywithFTP capabilities is a simplersolution. Once developers understand how to use that library, it’s easier fordevelopers to enhance or fix FTP logic in any of the applications in theenterprise.Asanotherexample,someapplicationsrequirebatchprocessing;thatis,processingnotinitiatedbyauserbutoccurringonadefinedschedule.Ifyouchoose one scheduler and standardize it across the enterprise, developers onlyhavetolearnoneschedulerproductandthatknowledgeiseasilytransferable.

REUSE—DON’TREINVENTTrend toward reusing components that exist rather than inventing newversionsofexistingcomponents.Thisprincipleappliestoapplicationandunittestcode.Italsoapplies tostoreddata(e.g., relationaldatabasedesignsshouldbe 3rd normal form to avoid multiple copies of the same information). ThisprincipleissometimesknownbytheacronymDon’tRepeatYourself(DRY).

Codereuse,bydefinition,reducesthesizeofthecodebaseasmeasuredbythenumberoflinesofcode.Codereuseoptimizesdevelopmenttime;it’softenfaster to reuse than reinvent.Code reuse also consolidatesmaintenance; a bugfixwithcommonlyusedcodepotentiallyfixesawidearrayofbugsasthesamecode is used inmultiple places. For example, consider a utility function usedacrosstheenterprisethatformsafullnamefromthefirst,middle,andlastnamesofaperson(i.e., turnsvalues“Derek,”“Clark,”and“Ashmore” into thestring“Ashmore,DerekClark”).Suppose thisutilityfunctionproducesanullpointerexceptionforpeoplewithoutrecordedmiddlenames.Thisbugmaywellsurfaceinmultipleapplicationsbutcouldbefixedinonecentralizedsectionofcode.

A corollary to the reuse principle is Don’t Repeat Others. Don’trebuild/rewritewhat’salreadyintheJDKoravailableinvendedoropensourceproducts. To this end, Apache Commons Lang, Commons IO, CommonsCollections,andCommonsBeanUtilsarefrequentadditionstomyapplications.Not only does this practice save development time; it saves testing time andreduces the likelihood of bugs. To illustrate the point, consider any of theproductsmentionedabove.Allofthemhaveextensiveunittestsuitesthathavebeendevelopedoveraperiodofyears.Furthermore, theseproductshavebeenfieldtestedinthousandsofproductsandapplicationsthroughouttheworld.Thisleveloftestcoveragefarexceedswhatyouwillbeabletoprovidewithcodeyoureinvent.

Centralizedomainorarchitecturespecificutilitycodeacrosstheenterprise.Organizationswithseveraldevelopmentteamsoftenhavesimilarifnotidenticalneeds. As I examine one of my current clients, I see sets of commonly usedHibernate entity classes that are shared/included in applications across thatorganization.Ialsoseeclassescommonforthespecifictechnicalproductstackthey’ve adopted: base classes for data access objects (DAO) classes, entityclasses,webserviceserverclasses,userinterfaceconverterclasses,forexample.Ialsoseeinterfaceclassesforinterfacingvendedproductstheyuse.Allofthese

are located separately in source control and are easily included in multipleapplications.

Centralizedcodeneedsstrictercodemanagement.Onemodelthateffectivelypolices common code is to appoint a small group of senior developers asadministrators for the centralized code. This ensures that code added to thecentralized library adheres to code quality and design standards and has unittests.Youcanviewthisgroupasthe“committer”groupforaninternalproduct.Whilecentralizingcodeat this leveldoes takeadditionalwork, thebenefits interms of saving development time across the enterprise can be large. If yourorganizationadoptsthesametechnicalproductsetformultipleapplications,youcan address cross-cutting concerns at an architecture level.Error handling andlogging should not be a concern for application developers for a specificapplication; the architecture should take care of that for you. Likewise,transaction management and security concerns can also be addressed at anarchitecturelevel.

Thereuseprinciplecanalsobeappliedtodatabasedesigns.Databasedesignsshouldbestrict3rdnormalformtoavoidrecordingthesamefactmultipletimes.Often, developers are tempted to break this paradigm under the label“denormalization”; I’ve discussed in a previous chapter the fact that this isn’tneededasmuchas itwasin thedayswhenrelationaldatabasetechnologywasnew. Essentially, recording the same data multiple times means that thoseadditionalcopiesneedtobemaintained.Theextracodeneededformaintainingthose additional copies of data is only necessary because multiple copies aremaintained.Bycentralizingfactsandonlyrecordingthemonce,youreducetheamountofmaintenancecodeneededoverall.

ENFORCESEPARATIONOFCONCERNSSoftwarecomponents shouldhaveanarrow focusandbeconcernedonlywithwhat they need to accomplish their objective; nothing more. Software“components”aredefinedloosely.Theycouldbeindividualclassesoraseparatelibrary.

The “separation of concerns” principle promotes simplicity since code tohandle unneeded information dependencies isn’t present. Components that arenarrowlyfocusedpromotereuse;theyareeasiertouseastheirpurposeisclearertodevelopersandmoreversatileandusefulinawidervarietyofcontexts.Thisprinciple makes software components easier to test as they reduce the

dependenciesthetestcodemustmanage.Thisprincipleeffectivelybreaksdowncomplexproblems into a series of simpler problems; it promoteswriting codewithaclearandconcisemission.Thereareseveralpracticalimplicationstothisprinciple,asfollows:

Applyingtheseparationofconcernsprinciplewillproducealargenumberof software components or classes. However, these classes will be muchsimplerandmoreversatile.Softwarelayering,whichisthepracticeofseparatingapplications into tiers, is an example of applying the separation of concernsprinciple. As you have seen in previous chapters, software layering producesmore classes, but each class has amore clearly defined role and purpose. Forexample, a data access class or DAO handles all reading and writing for aspecific entityordatabase table. Itspurpose is clear, and it caneasilybeusedandreusedinavarietyofcontextsandsometimesinavarietyofapplications.

Software components shouldhavea clearlydefinedmission.Anything elsewillleadtodeveloperconfusionandunnecessarycodecomplexity.Componentsthat havemultiplemissionsor uses are oftenmore complex and containmoreconditional logic than those classeswith a single purpose. Thismission focusmakesthecomponenteasiertouseandmoreversatile.Italsoreducestheneedtochange the software component as it has less responsibility. For example,embeddingbusinesslogicinDAOclasses(acommonmistakeIsee)makestheDAOmorecomplexandalsolessversatileasitnowmustassumeacallcontext.Hadthatbusinesslogicbeenseparatedout,itwouldbemucheasiertoreusethatDAOclassforotherfeaturesintheapplication.

Onlygivesoftwarecomponentsinformationthey“need”toaccomplishtheirtask.Providingunnecessaryinformationmakesthesoftwarecomponenthardertousebecausewhat’s important ishardtodistinguishfromwhat’sneeded.Forinstance,ifyouprovideaclassmethodafullcustomerentityclasswhenitonlyreally needs the customer’s first, middle, and last name, it’s unclear todeveloperswhichportionof thecustomerentity thecomponentactuallyneeds.Whenchangingthecustomerentity,thatcomponentwouldhavetobeexaminedforpossible impact.On theotherhand, if the threestringswere theargumentsfor that component method, changes to the customer entity class could notpossibly affect that component’s behavior. Avoid unnecessary parameters inmethods. Avoid unnecessary class-level fields. Expressed another way,componentsarelikespies;theyshouldoperateona“need-to-know”basis.

Individual classes and methods should not make assumptions aboutexecutioncontext. Inotherwords,classesandmethodsshouldbe independentandshouldn’tassumetheyareapartofalargercallsequence.Forexample,I’veseendevelopershardcodecommitsinDAOclasses,assumingthattheparticularDAOwillonlybeusedinaspecificusecase.ThislimitsuseofthatDAOclasssince it really can’t then be used in other use cases which have additionaldatabasewritestoperforminthesameunitofwork.Itwouldhavebeenbettertohandlethecommitorrollbackseparately;asit’sacross-cuttingconcern,Ioftenhandle commits and rollbacks using a servlet filter instead. Often, developershaveahardtimewiththisconcept.Theyhaveahardtimevisualizingusesforaparticular section of code other than the use case they’re currently concernedwith.

Don’texposemorefieldsandmethodsthanarenecessary.Thatis,protectedmethodsshouldbereferencesbyat least twoextendedclasses.Publicmethodsshouldbereferencesbyatleastoneexternalclass.Thisisacontinuationoftheneed-to-knowconcept.Exposed fields andmethods open the possibility that aclass is used in away thatwasn’t expected or tested. Put anotherway, if youexposefieldsormethods,youneedadditionalunit tests tocover theadditionalfunctionality.Oneexception that iscommonlymade forcomplexmethods thatwouldordinarilybemadeprivate is tomake themprotected, so that unit testscanbewrittentotestthemspecifically.Thishappensrarely,butitdoeshappen,and there is a benefit to promoting complex methods to protected status fortestingpurposes.

Don’tintroducedependenciesthataren’tneeded.Thisisacontinuationoftheneed-to-know concept.Unnecessary dependenciesmake components harder touse and test, as thesedependencies need to beprovided and any requirementstheyhaveinorder tofunctionneedtobemet.Forexample,onlyDAOclassesshouldbedependentonHibernateorJPAclasses.ForcodeinthebusinesslogiclayertohaveaHibernatedependencymeansthatHibernateneedstobeatleastpresentandpossiblyconfiguredforthatlogictorun.Thisplacesanextraburdenon unit test cases for these business logic classes. Additionally, it widens thepossibilityof impactshouldHibernatebeupgradedorswitchedtoanotherJPAimplementation.Youcanseethisconceptillustratedmoreclearlybylookingatthework you go through to introduce different third-party products into yourapplication. Introducing dependency-heavy products like Spring or Hibernateinvolve a lot more work as you typically need to examine potential version

conflicts for those dependencies. Conversely, introducing products withoutdependencies(e.g.,ApacheCommonsLang) isveryeasyas there ismuchlesspossibilityofversionconflicts.

Insulateallapplicationinterfacesusingproxies.Thatis,createaproxyclassfor all external applications used by your application. For example, if yourpurchasing application utilizes functionality in a customer managementapplicationviawebservices,createaproxyclassorclassesforthatactivity.Thislimits the effects of changes within the external application; changes to thatexternalapplicationwillaffecttheproxyclassonly.Also,thismakesunittestingeasierasyoucaneffectivelystubtheexternalapplication.Utilizingproxiesalsomakes it easy to log all requests/responseswith external applications tomakeproblemdiagnoseseasier.

SWIMWITHTHESTREAMUse products and technologies as they were intended to be used. Usingproductsinthewaytheywereintendedtobeusedincreasesthelikelihoodthatyour use of the product has been tested. Should you require assistance, thatassistanceandcodeexampleswillbeeasier toobtainformainstreamusesofaproductthanfornonstandardornonsanctionedusesoftheproduct.Thisistruewhetherit’savendedproductoranopensourceproduct.It’sjustthatwithopensourceproducts,your“support”isn’tprovidedbyavendorandusuallyconsistsofInternetsearchesorsearchesoftheproduct’sbuglists.

Usingtheproductasitwasmeanttobeusedincreasestheprobabilitythatyou will benefit from product advances. For example, users of relationaldatabasesthatuseddesignsin3rdnormalform(asrelationaldatabasesaremeanttobeused)requirefrequentjoins.Intheearlydays,thiswascauseforconcernsabout performance. Now, due to product advances, joins using primary andforeign keys usually present no performance issues whatsoever. Users whonormalized their database designs benefitted from technological advancementsmadetotherelationaldatabaseproductstheywereusing.

Don’tuse internalproduct classes thatwerenotmeant tobeusedoutsidetheproduct.This isanexampleof inappropriateusage. It iscommonforAPIproducts to have classes used internally that were never meant for publishedconsumption. For example, theweb service productApacheAxis has internalstringmanipulation classes used internallywithin theproduct. It is technically

possible for you to utilize those string manipulation classes and methods.However, theywerenever reallymeant tobe exposed tousersof theproduct.Thoseclassesarepublicsothattheycanbeusedbyseveralpackageswithintheproductandfornootherreason.Youruseof thoseinternalclassesmightworkforthecurrentversionoftheproductyou’reusing,butthoseinternalclassesaresubjecttochangewhenyouupgrade.Astheywerenevermeanttobeconsumedbyusers,littleornoeffortwillbemadetoensurethattheystillworkinthesameway.Inotherwords,yourriskofintroducingbugsduringanupgradeincreasesifyouhavebeenusingclassesandmethodsthatwerenevermeanttobeconsumed.While published interfaces of products can change (e.g., Hibernate seems tochangeitspublicallyconsumedAPIsquiteoften),thereisusuallydocumentationprovided for the change, with advice on how tomodify your applications onupgrade. This assistance usually doesn’t exist with internal classes that wereneverintendedforpublication.

CATCHERRORSEARLIERRATHERTHANLATERItisalwaysbettertocatchcodingerrorsasearlyinthedevelopmentprocessas possible. By ‘“better” we mean that errors caught earlier are generallycheapertofixandusuallycauselessdamage.Ifabugisdetectedbyendusers,then the bug at the very least negatively impacts end-user productivity andconsequentlyhasalaborcost.Dependingonthenatureofthebug,theenterprisemay incur other costs associated with the bug, such as inconveniencing andpotentially losingcustomers.Costsassociatedwith tracking,documenting, andeventuallyfixingthebugarealsopresent.Ontheotherhand,hadthatbugbeendetectedbeforedeploymenttoproduction,thebugwouldhavecostdevelopmenttimetofix,butpotentiallynoneoftheothercoststotheenterprisewouldhavebeenincurred.ThepracticesofTestDrivenDevelopment(TDD)andContinuousIntegration (CI) arebasedon thisprinciple. If nobodynotices the errorbeforeyoufixit,didtheerrorreallyoccur?

Therecommendedpracticeofcheckingargumentstoallpublicorprotectedmethodsappliesthisprinciple.Bycatchingandexplicitlylabelingtheerror,wesavedevelopmenttimefixingthebug.Asyouknow,derivativeerrorsareoftenharderandmoretimeconsumingtodiagnoseandfix.Therecommendedpracticeoftrendingtowardruntimeexceptionsappliesthisprinciplebymakingitmucheasierandsafertothrowanddescriptivelylabelerrorswithoutincurringthecost

of verbose try/catch logic. The recommended practice of providing an errornotificationmethodtosupportdevelopersappliesthisprinciplebyreportingtheerrorbeforeanenduserdoes.

Acorollary to thisprinciple is toadoptpractices thatpreventbugs in thefirstplace.Thepracticeofpairedprogramming,inwhichallcodeiswrittenbyateamoftwocoders,isanexampleofapplyingthisprinciple.Theideaisthatthe observing coder will catch errors that the typing coder misses and thusprevent bugs. Tools such as PMD for Find Bugs can scan your code andhighlightplacesinyourcodepronetocausingknowntypesofdefects,suchasnullpointerexceptions.

Automated error reporting and notification of support personnel isessential.Usersdon’treportallerrors.Ittakesworktofilloutahelpdeskticketorexplain theproblem toa technician inenoughdetail to reproduce.Often, ifusers can find a workaround, they’ll take the lazy way out and not report it.However, even though they don’t report the error, their perception of thesoftwareapplicationlowers.Consequently,automatederrorreportingistheonlyway you’ll get notified of some errors. Further, automated error reporting cangiveyouaclearervisionofhowfrequentlyusersencountertheerror.Inaddition,automatedreportswillarrivemorequickly,givingyoutheopportunitytoresolveissuesearlier.

Codethemosttechnicallyriskyportionsofaprojectfirst.Tasksthathavethelargest technical risk are generally those involving new or unfamiliartechnologiesorcontainingcomplexlogic.Errorsaremorelikelytobegeneratedfrom these aspects of the project than from any other. Consequently, codingthese sections first tends to increase the amount of testing time these sectionsreceiveandincreasesthechancethaterrorsarecaughtbeforerelease.

FUNCTIONALREQUIREMENTSARETHEHIGHESTPRIORITYAfunctionalrequirementisabusinessneed;itissomethingthatyourapplicationmustprovideforitsendusers.A“need”isafeatureessentialtotheoperationofthebusiness.Buildingapplications thatdon’tmeetbusinessneeds ispointless.Without a successful business side, there is no reason to sustain and fundbusiness applications and the architecture supporting them.The importance of

identifying functional requirements can’t be understated. This is why I havespent entire chapters guiding you in how to identify and document thoserequirements.Onewaytodocumentbusinessneedsisbyusecase,andtherearecertainlyothermethodologies.IlistthisasanarchitecturalprincipleasI’veseendevelopers sacrifice satisfying business requirements to preserve technicaldesignideals.Ifanapplicationarchitectureortechnicaldesigndoesn’tsupportanewbusinessrequirement,it’stimetoenhanceorreplacethatdesign.Wedon’tget to selectively ignore business requirements simply because they areinconvenient to program or they introduce additional complexity. Thecomplexityintroducedbyanewbusinessrequirementfrequentlyaddstothecostof developing and maintaining the applications supporting that requirement.Once users understand the costs of the requirements they express, they mayexpressthoseneedsdifferently.

It’s true that sometimes end-user representatives don’t clearly understandwhat those needs are or can’t express them effectively.Worded another way,sometimes clients don’t initially say what they reallymean. Sometimes, usersconfusea“need”witha“want.”A“need”isafeatureessentialtotheoperationof the business. A “want” is something that optimizes one portion of thatbusiness (e.g., reduces manual labor for someone) but isn’t essential to theoperationofthebusiness.Forexample,ausermay“want”anewreportdetailinginformation needed tomake business decisions. If the user has otherways toobtainthatinformation,thenewreportisa“want”(e.g.,itmakesgatheringtheinformation more convenient) but it is not a “need.” Ferreting out anddocumenting true business needs in detailed enough terms for softwaredeveloperstoimplementisaseparateandimportantskill.

Nonfunctional requirements are requirements that specify the conditionsunderwhichtheapplicationistooperate,butdon’tdefinespecificbehaviorslikefunctional requirements do. As an example of nonfunctional requirements, anapplication may require the presence of the Microsoft Windows operatingsystemwithatleast100MBofdiskspaceand2GBofmemory.AnotherexampleofanonfunctionalrequirementistobeaccessiblebytheuserovertheInternet.These requirements donot statewhat the application is used for or evenwhatbusiness requirements are satisfied. Ideally, nonfunctional requirements shouldneverdisruptsatisfyingbusinessneeds.

AbouttheAuthor

DerekAshmoreisaseniortechnologyexpertwithmorethantwenty-fiveyearsof experience in a wide variety of technologies and industries. His past rolesinclude application architect, enterprise architect, project manager, applicationdeveloper,anddatabaseadministrator.Hehasextensiveexperiencewithcustomapplication development as well as integrating applications with commercialproducts such as Great Plains, Sales Force, Microsoft Dynamics, and more.DerekhasbeendesigningandleadingJava-relatedprojectssince1999.

IfyouneedaprojectassessmentforyourJava-relatedproject,Derekcanberetainedbycontactingsales@dvtconsulting.com.

Derekcanbecontactedthefollowingways:

E-mail:derek.ashmore@dvtconsulting.comLinkedIn:http://www.linkedin.com/in/derekashmoreFacebook:https://www.facebook.com/JavaEEArchitectHandbook