== Transfer Configuration File ==

This configuration file defines the packages and objects that are created and produced by Transfer.

The xml schema file can be found at: [http://www.transfer-orm.com/transfer/resources/xsd/transfer.xsd /transfer/resources/xsd/transfer.xsd].

It is '''highly recommended''' that when creating a new transfer xml file, you validate your xml against this xml schema.

Items in ''italics'' denoted an element attribute.

=== Elements ===

<ul>
	<li>
               <span id="transfer"></span>
                '''transfer'''<br/>
		Top level element for the xml file.
		<ul>
			<li>
			<span id="includes"></span>
			'''includes''' (optional)<br/>
			Configure any include files that are used in the configuration of Transfer
				<ul>
					<li>
						'''include'''<br/>
						This is an include of a Transfer configuration file.<br/>
						''path'' The relative path from your application root to the include file.<br/>
						''overwrite (optional)'' Whether or not to overwrite the previous configurations.  Defaults to 'false'.
					</li>					
				</ul>
                        </li>
			<li>
				 <span id="objectCache"></span>
				'''objectCache''' (optional) <br/>

				Configure the settings for all object caching parameters.  If this is not set, the default values are used. More details on caching can be found at [[Managing the Cache]]
				<ul>
					<li>'''scopes''' (optional)
						Defines the keys that Transfer stores it's caching when using caching in shared scopes.
						If this is not set, the default values are used.
						<ul>
							<li>
								'''application''' (optional) <br/>
								The scope key for 'application' cached objects, if not set, all caching is done under the 'application.transfer' scope.
								<br/>
								''key'' The key to set the cache under, e.g. 'transfer'
							</li>
							<li>
								'''session''' (optional) <br/>
								The scope key for 'session', and cached objects, if not set, all caching is done under the 'session.transfer' scope.
								This also applies to 'transaction' scoped objects, as these caches share these scopes.
								<br/>

								''key'' The key to set the cache under, e.g. 'transfer'								
							</li>
							<li>
								'''request''' (optional) <br/>
								The scope key for 'request' cached objects, if not set, all caching is done under the 'request.transfer' scope.
								<br/>
								''key'' The key to set the cache under, e.g. 'transfer'
							</li>

							<li>
								'''server''' (optional) <br/>
								The scope key for 'server' cached objects, if not set, all caching is done under the 'server.transfer' scope.
								<br/>
								''key'' The key to set the cache under, e.g. 'transfer'
							</li>																					
						</ul>
					</li>

					<li>
						'''defaultcache''' (optional) <br/>
						This sets the default values for caching of objects within Transfer.  If this is not set, the default values are used.
						<ul>
							<li>
								'''maxobjects''' (optional) <br/>
								The maximum number of objects to store for any one Object class.  
								<br/>
								''value'' The number of TransferObjects to cache, defaults to unlimited (0).
							</li>
							<li>
								'''maxminutespersisted''' (optional) <br/>
								The maximum number of minutes to store any TransferObject of a given class. 
								<br/>
								''value'' The number of minutes to cache, defaults to unlimited (0).
							</li>
							<li>
								'''accessedminutestimeout''' (optional) <br/>
								The number of minutes in which a TransferObject will timeout in, if it has not been accessed. 
								<br/>
								''value'' Number of minutes until cache timeout, defaults to having no effect (0).
							</li>
							<li>
								'''scope''' (optional) <br/>
								The scope to store all TransferObjects under. Details on the types of caching available can found at [[Managing the Cache]]
								<br/>

								''type'' 'instance', 'application', 'session', 'request', 'transaction', 'server', 'none'.  Defaults to 'instance'
							</li>
						</ul>
					</li>
					<li>
						'''cache''' (optional) <br/>
						''class'' The class to set the caching settings for<br/>

						This overwrites the default settings for caching for a specific class
						<ul>
							<li>
								'''maxobjects''' (optional) <br/>
								The maximum number of objects to store for this class.  
								<br/>
								''value'' The number to cache, defaults to unlimited (0).
							</li>

							<li>
								'''maxminutespersisted''' (optional) <br/>
								The maximum number of minutes to store TransferObjects of this class. 
								<br/>
								''value'' The number of minutes to cache, defaults to unlimited (0).
							</li>
							<li>
								'''accessedminutestimeout''' (optional) <br/>
								The number of minutes in which a TransferObject will timeout in, if it has not been accessed. 
								<br/>
								''value'' Number of minutes until cache timeout, defaults to having no effect (0).
							</li>
							<li>
								'''scope''' (optional) <br/>
								The scope to store TransferObjects of this class under. Details on the types of caching available can found at [[Managing the Cache]].
								<br/>
								''type'' 'instance', 'application', 'session', 'request', 'transaction', 'server', 'none'.  Defaults to 'instance'
							</li>
						</ul>						
					</li>

				</ul>
			</li>
			<li>
				<span id="nullValues"></span>
				'''nullValues''' (optional) <br/>
				Configure the default null values for properties
				<ul>
					<li>
						'''string'''<br/>
						The default null value for all string types.<br/>
						''value'' The null value to use. Defaults to "".
					</li>
					<li>
						'''numeric'''<br/>
						The default null value for all numeric types.<br/>

						''value'' The null value to use. Defaults to 0.
					</li>
					<li>
						'''date'''<br/>
						The default null value for all date types.<br/>
						''value'' The null value to use. Defaults to 1/1/100.
					</li>

					<li>
						'''boolean'''<br/>
						The default null value for all boolean types.<br/>
						''value'' The null value to use. Defaults to 'false'.
					</li>
					<li>
						'''UUID'''<br/>

						The default null value for all UUID types.<br/>
						''value'' The null value to use. Defaults to '00000000-0000-0000-0000000000000000'.
					</li>
					<li>
						'''GUID'''<br/>
						The default null value for all GUID types.<br/>
						''value'' The null value to use. Defaults to '00000000-0000-0000-0000-000000000000'.
					</li>																													
                                        <li>
                                        '''binary'''<br/>
                                        The default null value for all binary types. <br/>
                                        ''value'' The null value to use (Whatever is written here is converted to a Java byte array). Defaults to empty byte array.
                                        </li>
				</ul>

			</li>
			<li>
			
				'''objectDefinitions'''<br/>
				All the Object definitions
				<ul>
					<li>
						'''package'''
						<br/>
						Organisational element to store various objects of similar aspect together. e.g. a 'user' package.
						<br/>
						''name'' The name of the package
						<ul>
							<li>
								'''object''' <br/>
								Package can contain multiple object elements
							</li>

							<li>
								'''package'''<br/>
								Package can contain multiple package elements
							</li>
						</ul>
					</li>
					<li>
						'''object'''<br/>
						A class definition for a [http://docs.transfer-orm.com/html/transferapi/transfer/com/TransferObject.html transfer.com.TransferObject]
						to be 
						manufactured into a bean that represents a record in the set
						database table.
						<br/>
						''name'' The name of the TransferObject, e.g. 'User'.
						<br/>
						''table (optional)'' The database table that the TransferObject refers to, e.g. 'tbl_User'. 
						Defaults to the value of @name
						<br/>
						''decorator (optional)''
						The value of a ColdFusion component that extends [http://docs.transfer-orm.com/html/transferapi/transfer/com/TransferDecorator.html transfer.com.TransferDecorator] and will
						decorate the generated TransferObject.  Details on Decorators can be found at [[Writing Decorators]]
						<br/>
						''sequence (optional)'' Specifically for Oracle and PostGreSQL support.  This is the
						name of the sequence that corresponds with this object's table.  Defaults to the value of @table + '_seq'
						<br/>						
						''tablealias (optional)''
						This is an table alias that will be used for get() operations in Transfer. This is usually most useful for Oracle when the generated alias is over 30 characters.
						<ul>
							<li>
                                  				<span id="id"></span>
								'''id'''<br/>
								This is the definition of the primary key as set in the database.<br/>
								This results in getter and setter functions
								on the TransferObject.
								Details on all these methods can be found at
                                                                [[Generated Methods#id]].<br/>
								There can only be one ID declaration, but either 'id' or 'compositeid' must be present.
								<br/>
								''name'' The name of the ID, e.g. 'IDUser'
								<br/>
								''type''
								The typing of the primary key, either numeric, string, date, boolean, UUID, GUID, binary.
								<br/>
								''column (optional)''
								The primary key column on the table of this TransferObject. e.g. 'IDUser'.
								Defaults to the value of @name.
								<br/>
								''generate (optional)'' If this is set to true, Transfer will generate the primary key when the record is inserted into the database. Otherwise it will assume that the primary key is automatically generated by the database.  Transfer currently supports generating numeric, UUID, and GUID IDs.  Defaults to false.
							</li>
							<li>
                                  				<span id="compositeid"></span>
								'''compositeid'''<br/>
								A composite key declaration, which contains any combination of foreign key relationships and/or property values.
								This results in a 'getCompositeID()' function on the TransferObject. Details on all these methods can be found at [[Generated Methods#compositeid]].
								There can only be one compositeid declaration, but either 'id' or 'compositeid' must be present.
								<ul>
									<li>
										'''property (optional)'''<br/>
										The property to use in this composite id. The 'property' element can be used more than once.<br/>
										''name'' The name attribute matches the name attribute of a configured property within the object.
									</li>
									<li>
										'''manytoone (optional)'''<br/>
										The manytoone relationship to use in this composite id. This represents the usage of a foreign key in the composite id.
										The 'manytoone' element can be used more than once.<br/>
										''name'' The name attribute matches the name element of a configured manytone element within the object. 
									</li>
									<li>
										'''parentonetomany (optional)'''<br/>
										The parent onetomany relationship to use in this composite id. This represents the usage of a foreign key in the composite id.
										The 'parentonetomany' element can be used more than once.<br/>
										''class'' The name attribute matches the name element of a configured manytone element within the object.
									</li>
								</ul>
							</li> 
							<li>
                                  				<span id="property"></span>
								'''property'''<br/>
								A single property on the TransferObject.<br/>
								This results in getter and setter functions
								on the TransferObject.
								Details on these methods can be found at
                                                                [[Generated Methods#property]]
								.<br/>
								Default values for these properties can be found in [[Default Property Values]]<br/>
								TransferObjects can have multiple property declarations.
								<br/>
								''name'' The name of the property, e.g. 'Name'
								<br/>
								''type''
								The type of the property. Either numeric, string, date, boolean, UUID, GUID, binary.
								<br/>
								''column (optional)''
								The column on the table this property refers to, e.g. 'user_Name'. Defaults to the value of @name
								<br/>
								''set (optional)''
								If this is set to 'false' the setter function has a scope of private. Defaults
								to 'true'.
								<br/>
								''nullable (optional)''
								Defines whether or not values from this property can be inserted into the database as NULL values.
								<br/>
								''nullvalue (optional)''
								Overrides the default null value for this property. Only relevant if @nullable='true'.
								<br/>
								''ignore-insert (optional)''
									Will ignore this property when performing an insert of this object into its table.
								<br/>
								''refresh-insert (optional)''
									This will query the database for the value of this column and refresh its state
									after an insert.
								<br/>
								''ignore-update (optional)''
									Will ignore this property when performing an update of this object into its table.
								<br/>
								''refresh-update (optional)''
									This will query the database for the value of this column and refresh its state
									after an update.								
							</li>

							<li>
                                                               <span id="manytoone"></span>
								'''manytoone'''
								<br/>
								This defines a relationship when many of a this object's table records
								link directly to one of another tables. e.g. 'tbl_User.lnkIDPermission = tbl_Permission.IDPermission'.<br/>
								It creates getter and setter functions on the TransferObject that get and set 
								the composite TransferObject.  Details on these methods can be found at [[Generated Methods#manytoone]].<br/>
								TransferObjects can have multiple manytoone declarations.
                                                                <messagebox type="warning">You can only have one manytoone or oneotomany definition for each foreign key. You may also not share a foreign key used in a manytoone with a <property> definition</messagebox>
								''name''
								The name of this relationship, e.g. 'Permission'.
								<br/>
								''lazy (optional)''
								If this is set to 'true', the manytoone composition will only be loaded when requested.
								This defaults to 'false'.  For more information, see [[Using Lazy Loading]].
                                                                <br/>
                                                                ''proxied (optional)''
								If this is set to 'true', only a proxy of the TransferObject will be loaded, rather than the full object data, for each TransferObject.
								Default is 'false'.  For more information, see [[Using TransferObject Proxies]].
								<ul>
									<li>
										'''link'''<br/>
										Defines what other TransferObject the composition is made up of.
										<br/>
										''to''
										The class name of the TransferObject this links to, e.g. 'user.Permission'.
										<br/>
										''column''
										The column on the parent TranferObject table that is the foreign key to the composite child, 
										e.g. 'lnkIDPermission'.
									</li>
								</ul>

							</li>
							<li>
                                                               <span id="onetomany"></span>
								'''onetomany'''<br/>
								This defines a relationship where one of this object's table records corresponds 
								to many of another tables records. e.g. 'tbl_User.IDUser = tbl_Post.lnkIDUser'.<br/>
								This creates several methods on the parent and child TransferObjects, dependent on the set
								collection type. 
								Details on all these methods can be found at [[Generated Methods#onetomany]].<br/>
								TransferObjects can have multiple one to many declarations.
                                                                <messagebox type="warning">You can only have one oneotomany or manytoone definition for each foreign key. You may also not share a foreign key used in a manytoone with a <property> definition</messagebox>
								''name''
								The name of this collection, e.g. 'Permission'.
								<br/>
								''lazy (optional)''
								If this is set to 'true', the onetomany composition will only be loaded when requested.
								This defaults to 'false'.  For more information, see [[Using Lazy Loading]].
                                                                <br/>
                                                                ''proxied (optional)''
								If this is set to 'true', only a collection of proxies of the TransferObject will be loaded, rather than the full object data, for each TransferObject.
								Default is 'false'.  For more information, see [[Using TransferObject Proxies]].							
								<ul>
									<li>
										'''link'''<br/>
										Defines the TransferObject the composition is made up of.
										<br/>
										''to''
										The class name of the TransferObject this links to, e.g. 'user.Permission'.
										<br/>
										''column''
										The column on the child TranferObject table that is the foreign key to the parent, 
										e.g. 'lnkIDUser'.
									</li>
									<li>

										'''collection'''<br/>
										This element sets the details of the type of collection of TransferObject
										that is added to the parent.
										<br/>
										''type'' Either 'struct' or 'array'. If 'struct' is selected, a structure is
										used to manage the composite TransferObjects, whereas an array is used when the type 
										is set to 'array'.
										<ul>
											<li>
												'''condition''' (Optional) Used to place a filtering condition on the 
												child elements that are retrieved from the database.
												<br/>

												''property (optional)''
												The property on the child object to filter by.
												<br/>
												''value (required if property has a value)''
												The value of the property to filter by.
												<br/>
												''where (required if property/value is not set)''
												The SQL statement to filter the child object by. 
												Child properties enclosed with '{}' will be resolved to their column names.
											</li>

											<li>
												'''key''' (if ''collection[@type]'' = 'struct')<br/>
												The property to be used in the key when adding and retrieving
												items from parent. This property much have a unique value.
												<br/>
												''property'' The name of the property on the child TransferObject
												to be used as the key, 									
												e.g. 'permissionName'.
											</li>

											<li>
												'''order''' (optional if ''collection[@type]'' = 'array')<br/>
												The order in which to sort the collection.
												<br/>
												''property'' The name of the property on the child TransferObject
												to sort the array by.
												<br/>

												''order'' The order to sort by, either 'asc' or 'desc'.
											</li>
										</ul>
									</li>
								</ul>
							</li>
							<li>
                                                               <span id="manytomany"></span>
								'''manytomany'''<br/>
								This defines a relationship where many of this object's table records corresponds
								to many of another tables.  This is normally accomplished at a database level by
								use of an intermediary linking table.
								e.g. 
								'tbl_User.IDUser = lnk_UserPermssion.lnkIDUser
								AND
								lnk_UserPermission.lnkIDPermission = tbl_Permission.IDPermission'.<br/>
								This creates several methods on the parent TransferObject, dependent on the set
								collection type. 
								Details on all these methods can be found at
								[[Generated Methods#manytomany]].<br/>
								TransferObjects can have multiple manytomany declarations.
                                                                <messagebox type="warning">You can only have one manytomany definition for each linking table. Bi-directional manytomany is not yet supported.</messagebox>
								''name''
								The name of this collection, e.g. 'Permission'.
								<br/>
								''table''
								The name of the intermediary table that creates the many to many relationship. 
								e.g. 'lnk_UserPermission'
								<br/>
								''lazy (optional)''
								If this is set to 'true', the manytomany composition will only be loaded when requested.
								This defaults to 'false'.  For more information, see [[Using Lazy Loading]].
                                                                <br/>
                                                                ''proxied (optional)''
								If this is set to 'true', only a collection of proxies of the TransferObject will be loaded, rather than the full object data, for each TransferObject.
								Default is 'false'.  For more information, see [[Using TransferObject Proxies]].
								<br/>
								''tablealias (optional)''
								This is an table alias that will be used for get() operations in Transfer. This is usually most useful for Oracle when the generated alias is over 30 characters.								
								<ul>
									<li>
										'''link'''<br/>

										The first link specifies the connection information for the 
										intermediary table to the parent table.
										<br/>
										''to''
										This first link MUST be the same class name as the Parent TransferObject. e.g. 'user.User'
										<br/>
										''column''
										This is the column on the intermediary table that is the foreign key
										to the parent TransferObject's table, e.g. 'lnkIDUser'
									</li>
									<li>

										'''link'''<br/>
										The second link defines the TransferObject the composition is made up of.
										<br/>
										''to''
										This second link is the class name to the child TransferObject, e.g. 'user.Permission'.
										<br/>
										''column''
										This is the column on the intermediary table that is the foreign key
										to the child TransferObject's table, e.g. 'lnkIDPermission'				
									</li>

									<li>
										'''collection'''<br/>
										This element sets the details of the type of collection of TransferObject
										that is added to the parent.
										<br/>
										''type'' Either 'struct' or 'array'. If 'struct' is selected, a structure is
										used to manage the composite TransferObjects, whereas an array is used when the type 
										is set to 'array'.
										<ul>
											<li>
												'''condition''' (Optional) Used to place a filtering condition on the 
												child elements that are retrieved from the database.
												<br/>

												''property (optional)''
												The property on the child object to filter by.
												<br/>
												''value (required if property has a value)''
												The value of the property to filter by.
												<br/>
												''where (required if property/value is not set)''
												The SQL statement to filter the child object by. 
												Child properties enclosed with '{}' will be resolved to their column names.
												</li>

											<li>
												'''key''' (if ''collection[@type]'' = 'struct')<br/>
												The property to be used in the key when adding and retrieving
												items from parent. This property much have a unique value
												<br/>
												''property''The name of the property on the child TransferObject
												to be used as the key, 									
												e.g. 'permissionName'.
											</li>

											<li>
												'''order''' (optional if ''collection[@type]'' = 'array')<br/>
												The order in which to sort the collection.
												<br/>
												''property'' The name of the property on the child TransferObject
												to sort the array by.
												<br/>

												''order'' The order to sort by, either 'asc' or 'desc'.
											</li>
										</ul>
									</li>
								</ul>
							</li>
							<li>
								<span id="function"></span>
								'''function'''<br/>
								A cfml function that you want added to this TransferObject.<br/>
								TransferObjects can have multiple function declarations.
								<br/>
								Details on custom methods can be found at
								[[Custom Methods]].
								<br/>
								''name'' The name of the function<br/>

								''access'' Access of the function, public, private or package.<br/>
								''returntype'' Type of what is returned by this function.<br/>
								<ul>
									<li>
										'''argument'''<br/>

										A defined argument for the function<br/>
										A Function can have multiple function declarations.
										<br/>
										''name'' The name of the argument<br/>
										''type'' The type of the argument<br/>
										''required (optional)'' If the argument is required, defaults to 'false'.<br/>

										''default (optional)'' The default value for this argument if it is not set. <br/>
									</li>
									<li>
										'''body'''<br/>
										The cfml body of the function.  It may be neccessary to utilise a CDATA declaration in this area.<br/>
										There can only be one body declaration per function.
									</li>

								</ul>
								
							</li>
						</ul>
					</li>
				</ul>				
			</li>
		</ul>
	</li>
</ul>


[[Category:Configuration]]