Data Mapper Guide-1.6.2

DataMapperDeveloperGuideVersion1.6.1March2007Copyright2003-2005TheApacheSoftwareFoundationAuthors-TedHusted,GillesBayon,ClintonBegin,RobertoRabeCopiesofthisdocumentmaybemadeforyourownuseandfordistributiontoothers,providedthatyoudonotchargeanyfeeforsuchcopiesandfurtherprovidedthateachcopycontainsthisCopyrightNotice,whetherdistributedinprintorelectronically.TableofContents1.Introduction...11.1.Overview...11.2.What'scoveredhere...11.3.Releasechangelog...11.4.LicenseInformation...21.5.Support...21.6.Disclaimer...22.TheBigPicture...32.1.Introduction...32.2.Whatdoesitdo?...32.3.Howdoesitwork?...32.4.IsiBATISthebestchoiceformyproject?...53.WorkingwithDataMaps...73.1.Introduction...73.2.What'sinaDataMapdefinitionfile,anyway?...73.3.MappedStatements...93.3.1.StatementTypes...103.3.2.StoredProcedures...113.3.3.TheSQL...123.3.4.Statement-typeElementAttributes...153.4.ParameterMapsandInlineParameters...203.4.1.parameterMapattributes...213.4.2.parameterElements...223.4.3.InlineParameterMaps...233.4.4.StandardTypeParameters...253.4.5.MaporIDictionaryTypeParameters...253.5.ResultMaps...263.5.1.ExtendingresultMaps...273.5.2.resultMapattributes...273.5.3.constructorelement...273.5.4.resultElements...293.5.5.CustomTypeHandlers...323.5.6.InheritanceMapping...353.5.7.ImplicitResultMaps...383.5.8.PrimitiveResults(i.e.String,Integer,Boolean)...393.5.9.MapswithResultMaps...403.5.10.ComplexProperties...403.5.11.AvoidingN+1Selects(1:1)...413.5.12.ComplexCollectionProperties...433.5.13.AvoidingN+1SelectLists(1:MandM:N)...433.5.14.CompositeKeysorMultipleComplexParametersProperties...453.6.SupportedTypesforParameterMapsandResultMaps...463.7.SupporteddatabasetypesforParameterMapsandResultMaps...483.8.CacheModels...493.8.1.Read-Onlyvs.Read/Write...493.8.2.SerializableRead/WriteCaches...503.8.3.CacheImplementation...503.8.4.MEMORY...50DataMapperGuideVersion1.6.1ii3.8.5.LRU...513.8.6.FIFO...523.9.DynamicSQL...523.9.1.BinaryConditionalElements...543.9.2.UnaryConditionalElements...553.9.3.ParameterPresentElements...563.9.4.IterateElement...573.9.5.SimpleDynamicSQLElements...574..NETDeveloperGuide...594.1.Introduction...594.2.InstallingtheDataMapperfor.NET...594.2.1.SetuptheDistribution...594.2.2.AddAssemblyReferences...604.2.3.AddXMLFileItems...614.2.4.VisualStudio.NETIntegration...614.3.ConfiguringtheDataMapperfor.NET...624.3.1.DataMapperclients...624.3.2.DataMapperConfigurationFile(SqlMap.config)...634.3.3.DataMapperConfigurationElements...634.4.ProgrammingwithiBATISDataMapper:The.NETAPI...734.4.1.BuildingaSqlMapperInstance...734.4.2.ExploringtheDataMapperAPIthroughtheSqlMapper...784.4.3.Session...834.4.4.Connection...834.4.5.AutomaticSession...834.4.6.Transaction...844.4.7.DistributedTransactions...854.4.8.CodingExamples[TODO:ExpandintoaCookbookofpracticalexamples]...864.5.LoggingSqlMapActivity...874.5.1.SampleLoggingConfigurations...89A.iBATIS.NET'sSqlMapConfig.xsd...93B.iBATIS.NET'sSqlMap.xsd...95iBATIS.NET-DataMapperApplicationFrameworkDataMapperGuideVersion1.6.1iiiChapter1.Introduction1.1.OverviewTheiBATISDataMapperframeworkmakesiteasiertouseadatabasewithaJavaor.NETapplication.iBATISDataMappercouplesobjectswithstoredproceduresorSQLstatementsusingaXMLdescriptor.SimplicityisthebiggestadvantageoftheiBATISDataMapperoverobjectrelationalmappingtools.TouseiBATISDataMapperyourelyonyourownobjects,XML,andSQL.Thereislittletolearnthatyoudon'talreadyknow.WithiBATISDataMapperyouhavethefullpowerofbothSQLandstoredproceduresatyourfingertips.1.2.What'scoveredhereThisGuidecoversthe.NETimplementationsofiBATISDataMapper.TheJavaimplementationoffersthesameserviceswithsomechangesintheAPI.SinceiBATISreliesonanXMLdescriptortocreatethemappings,muchofthematerialappliestobothimplementations.Forinstallationinstructions,seethesectioncalledthe.NETDeveloperGuide.ATutorialisalsoavailable.WerecommendreviewingtheTutorialforyourplatformbeforereadingthisGuide.TipIfyouwouldliketogetthelatestdevelopment(unreleased)versionofthisGuide,pleaseseetheiBATISWikiFAQ[].TheFAQentryexplainshowyoucanaccessourSVNsourcerepositoryandgenerateCHMandPDFfilesofthelatestdevelopmentdocumentationfortheDataMapper.1.3.ReleasechangelogVersion1.6.0•ResolutionofN+1selectproblemusinggroupByattribute•AddedsupportofreuseSQLfragementviainclude/tag•Addedlazyloadsupportforsingleclass•AddedsupportforIDictionaryK,VQueryForDictionaryK,V(...)•MarkedQueryForPaginatedListasobsolete•AllowedprocedurestatementwithoutparameterMap•RemovedobsoletesmethodsonSqlMapper:DataMapperGuideVersion1.6.11Configure(XmlDocumentdocument),Configure(),Configure(stringresource),ConfigureAndWatch(ConfigureHandlerconfigureDelegate),ConfigureAndWatch(stringresource,ConfigureHandlerconfigureDelegate)•ExtendeduseofISqlMapperinDataMapper+alloweduseofacustomISqlMapper.•AllowedcustomISessionStore.1.4.LicenseInformationiBATIS.NETislicensedaccordingtothetermsoftheApacheLicense,Version2.0.Thefulltextofthislicenseareavailableonlineat