Update of /cvsroot/xdoclet/xdoclet/xdocs
In directory sc8-pr-cvs1:/tmp/cvs-serv2453
Modified Files:
valueobjects.xml
Log Message:
addition of an email on the list
Index: valueobjects.xml
===================================================================
RCS file: /cvsroot/xdoclet/xdoclet/xdocs/valueobjects.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** valueobjects.xml 17 Dec 2002 15:53:37 -0000 1.1
--- valueobjects.xml 17 Dec 2002 16:33:45 -0000 1.2
***************
*** 5,12 ****
<title>Using Value Objects</title>
</properties>
! <body>
!
! <section name="Motivation">
! <p>
The <valueobject> task is the xdoclet embodiement of the Value
Object pattern, as described in <em>Core J2EE Patterns</em>.
--- 5,11 ----
<title>Using Value Objects</title>
</properties>
! <body>
! <section name="Motivation">
! <p>
The <valueobject> task is the xdoclet embodiement of the Value
Object pattern, as described in <em>Core J2EE Patterns</em>.
***************
*** 15,19 ****
some EJB shortcomings.
</p>
! <p>
Every remote enterprise bean call may go through the network,
implying a heavy performance penalty. For entity beans this is specially
--- 14,18 ----
some EJB shortcomings.
</p>
! <p>
Every remote enterprise bean call may go through the network,
implying a heavy performance penalty. For entity beans this is specially
***************
*** 23,27 ****
would make a remote call for each property. No, no good.
</p>
! <p>
The solution is to create a coarse-grained object that contains some
or all the bean properties and provide a method to create this object
--- 22,26 ----
would make a remote call for each property. No, no good.
</p>
! <p>
The solution is to create a coarse-grained object that contains some
or all the bean properties and provide a method to create this object
***************
*** 31,39 ****
values. The following diagram illustrates this approach.
</p>
! <p>
{{{@todo: INSERT UML DIAGRAM HERE}}}
</p>
! <subsection name="Multiple Value Objects Strategy">
! <p>
Suppose you have defined a <code>Customer</code> entity with properties
such as id, name, birth date, full address, number of children,
prefered
--- 30,38 ----
values. The following diagram illustrates this approach.
</p>
! <p>
{{{@todo: INSERT UML DIAGRAM HERE}}}
</p>
! <subsection name="Multiple Value Objects Strategy">
! <p>
Suppose you have defined a <code>Customer</code> entity with properties
such as id, name, birth date, full address, number of children,
prefered
***************
*** 45,49 ****
millions of them.
</p>
! <p>
In a scenario like the one above, it would be useful to define
multiple value objects, each one containing a different set of
--- 44,48 ----
millions of them.
</p>
! <p>
In a scenario like the one above, it would be useful to define
multiple value objects, each one containing a different set of
***************
*** 52,66 ****
customer ID and name.
</p>
! <p>
Your entity bean would provide methods to obtain both value objects,
and perhaps methods to update the entity from both of them.The
following
diagram illustrates this approach.
</p>
! <p>{{{INSERT UML DIAGRAM HERE}}}</p>
! </subsection>
! </section>
!
! <section name="Using Value Objects in XDoclet">
! <p>
XDoclet helps you to define and create your value objects. Below you
can see a xdoclet-taged Entity Bean source code, with @tags related to
--- 51,64 ----
customer ID and name.
</p>
! <p>
Your entity bean would provide methods to obtain both value objects,
and perhaps methods to update the entity from both of them.The
following
diagram illustrates this approach.
</p>
! <p>{{{INSERT UML DIAGRAM HERE}}}</p>
! </subsection>
! </section>
! <section name="Using Value Objects in XDoclet">
! <p>
XDoclet helps you to define and create your value objects. Below you
can see a xdoclet-taged Entity Bean source code, with @tags related to
***************
*** 70,74 ****
Objects are presented here.
</p>
! <source>
package example.ejb;
--- 68,72 ----
Objects are presented here.
</p>
! <source>
package example.ejb;
***************
*** 174,178 ****
}
</source>
! <p>
As you can see, there is only one tag you need to write to instruct
xdoclet to generate value objects: <code>@ejb.value-object</code>.
--- 172,176 ----
}
</source>
! <p>
As you can see, there is only one tag you need to write to instruct
xdoclet to generate value objects: <code>@ejb.value-object</code>.
***************
*** 181,186 ****
xdoclet.
</p>
! <subsection name="Value Object Declaration">
! <p>
The first thing to do is to inform xdoclet which value objects it
will generated for your bean. At class level, introduce the
--- 179,184 ----
xdoclet.
</p>
! <subsection name="Value Object Declaration">
! <p>
The first thing to do is to inform xdoclet which value objects it
will generated for your bean. At class level, introduce the
***************
*** 193,197 ****
generated: <code>CustomerValue</code> and
<code>CustomerLightValue</code>.
</p>
! <p>
The <code>match</code> parameter will tell xdoclet which entity
properties will be included in the generated value object. It's just
--- 191,195 ----
generated: <code>CustomerValue</code> and
<code>CustomerLightValue</code>.
</p>
! <p>
The <code>match</code> parameter will tell xdoclet which entity
properties will be included in the generated value object. It's just
***************
*** 203,209 ****
only the <code>id</code> and <code>name</code> properties.
</p>
! </subsection>
! <subsection name="Aggregation and Composition">
! <p>
Value objects can have <code>composite</code> and
<code>aggregate</code>
properties. These are multivalued properties that map an EJB
relationship.
--- 201,242 ----
only the <code>id</code> and <code>name</code> properties.
</p>
! </subsection>
! <subsection name="How Relationships Work">
! <p>Starting with a given source entity and the target
on the other side of a relation,
! there are 1:1, 1:n, n:1, and n:n relations. </p>
! <p>Internally to XDoclet, a relation is tracked
separately of either side of the
! relation using the name attribute of ejb:relation. If both sides of a
! relation have an @ejb:relation tag with a matching name attribute (the
"name"
! attribute is the key that is used to uniquely identify the relationship),
! information that would otherwise be incomplete can be inferred. But when the
! target relation does not have corresponding reverse visibility of the source
! in the relation and there is no @ejb:relation tag in the target with a
! matching name attribute, there are *some* cases where additional information
! needs to be provided to XDoclet in lieu of the missing information. The
! @ejb:target-relation tag provides the ability to provide this information.
! Thus, it is only needed or used when there is one-way visibility on a
! relation and the information that would normally be provided at the target is
! critical to the complete set of information that is necessary to generate the
! information about the relation as a whole.</p>
! <p>The primary case of where this is necessary is
where you have an 1:n
! unidirectional link (there is no link visibility on the n side of the link).
! Since 1:n links are modeled with the n side keeping a foreign key reference
! of the 1 side, attempting to generate a 1:n link without reverse visibility
! leaves XDoclet without the critical information it needs to know: the
! related-pk-field attribute. Using the target-relation tag allows this
! information to be provided. It's possible to model a 1:1 link this way,
! where the schema visibility is target-to-source, but the desired design
! visibility is source to target (for example, creating a new application on
! top of a legacy schema.) In this case the target-relation tag is used to
! describe the schema details, even though the generated APIs are reversed of
! that and under normal 1:1 circumstances, it would be fine to store the
! foreign key in the source entity.</p>
! <p>n:n and n:1 relations are the easy cases, because
the source entity contains
! the foreign key of the related entity. Whether or not there is reverse
! visibility is irrelevant to XDoclet since it has all the information it needs
! about the relation in the ejb:relation tag.</p>
! </subsection>
! <subsection name="Aggregation and Composition">
! <p>
Value objects can have <code>composite</code> and
<code>aggregate</code>
properties. These are multivalued properties that map an EJB
relationship.
***************
*** 212,216 ****
respectively.
</p>
! <p>
Aggregation should be used when the related object is not directly
dependant on the one we're declaring the value object.
--- 245,249 ----
respectively.
</p>
! <p>
Aggregation should be used when the related object is not directly
dependant on the one we're declaring the value object.
***************
*** 221,225 ****
them via the generated <code>addPreferredProduct()</code> method.
</p>
! <p>
Composition should be used when the related object is directly
dependent on the one we're declaring the value object, and cannot
--- 254,258 ----
them via the generated <code>addPreferredProduct()</code> method.
</p>
! <p>
Composition should be used when the related object is directly
dependent on the one we're declaring the value object, and cannot
***************
*** 232,236 ****
<code>addAddress()</code> and <code>removeAddress()</code> methods.
</p>
! <p>
Aggregation and composition may be confusing at first. As a rule of
thumb, considers object creation responsibility: if the entity we're
--- 265,269 ----
<code>addAddress()</code> and <code>removeAddress()</code> methods.
</p>
! <p>
Aggregation and composition may be confusing at first. As a rule of
thumb, considers object creation responsibility: if the entity we're
***************
*** 240,244 ****
difference between the two.
</p>
! <p>
Now let's break down the many parameters that are needed to
accomplish a multivalued property on a value object. The
--- 273,277 ----
difference between the two.
</p>
! <p>
Now let's break down the many parameters that are needed to
accomplish a multivalued property on a value object. The
***************
*** 249,253 ****
multivalued properties uses <code>Collection</code> as type.
</p>
! <p>
The <code>aggregate-name</code> (or <code>composite-name</code>)
parameter tells xdoclet how the accessor methods to this property in
--- 282,286 ----
multivalued properties uses <code>Collection</code> as type.
</p>
! <p>
The <code>aggregate-name</code> (or <code>composite-name</code>)
parameter tells xdoclet how the accessor methods to this property in
***************
*** 258,262 ****
the aggregate-name for the relationship.
</p>
! <p>
The <code>aggregate</code> (or <code>composite</code>) parameter
tells xdoclet which should be the type of itens contained in
--- 291,295 ----
the aggregate-name for the relationship.
</p>
! <p>
The <code>aggregate</code> (or <code>composite</code>) parameter
tells xdoclet which should be the type of itens contained in
***************
*** 267,271 ****
starting to make sense, no?
</p>
! <p>
The <code>members</code> parameter tells xdoclet the fully qualified
type of the related objects. This should be the type of the objects
--- 300,304 ----
starting to make sense, no?
</p>
! <p>
The <code>members</code> parameter tells xdoclet the fully qualified
type of the related objects. This should be the type of the objects
***************
*** 280,284 ****
parameter.
</p>
! <p>
The <code>members-name</code> parameter should be the name of the
method in the related object that xdoclet should use to get the
--- 313,317 ----
parameter.
</p>
! <p>
The <code>members-name</code> parameter should be the name of the
method in the related object that xdoclet should use to get the
***************
*** 289,293 ****
<code>preferedProducts</code> property. Are you still with me?
</p>
! <p>
Last, the <code>relation</code> parameter, which only accepts the
<code>external</code> value tells xdoclet that this property can be
--- 322,326 ----
<code>preferedProducts</code> property. Are you still with me?
</p>
! <p>
Last, the <code>relation</code> parameter, which only accepts the
<code>external</code> value tells xdoclet that this property can be
***************
*** 297,303 ****
parameter.
</p>
! </subsection>
! <subsection name="Exposing Generated Methods">
! <p>
Please notice the last three methods in this example. The Bean
implementation class generated by xdoclet will contains them, but by
--- 330,336 ----
parameter.
</p>
! </subsection>
! <subsection name="Exposing Generated Methods">
! <p>
Please notice the last three methods in this example. The Bean
implementation class generated by xdoclet will contains them, but by
***************
*** 311,334 ****
however.
</p>
! </subsection>
! </section>
! <section name="Customizing the &lt;valueobject&gt; task">
! <p>
The <code>&lt;valueobject&gt;</code> task can be customized to
your liking, to change things like the name of the package where the
generated classes go and the name of the generated value objects.
</p>
! <p>
You can change the target package using a nested
! <a
!
href="ant/xdoclet/tagshandler/PackageTagsHandler.PackageSubstitution.html"><code>&lt;packageSubstitution&gt;</code></a>
element. For example, suppose we want all our value objecs generated
under the <code>example.valueobjects</code> package.
</p>
! <source><![CDATA[<valueobject>
<packageSubstitution packages="ejb" substituteWith="valueobjects"/>
! </valueobject>]]>
! </source>
! <p>
This tells xdoclet to substitute all packages names ending in "ejb" with
a package name ending in "valueobject". The
--- 344,367 ----
however.
</p>
! </subsection>
! </section>
! <section name="Customizing the &lt;valueobject&gt; task">
! <p>
The <code>&lt;valueobject&gt;</code> task can be customized to
your liking, to change things like the name of the package where the
generated classes go and the name of the generated value objects.
</p>
! <p>
You can change the target package using a nested
! <a href="ant/xdoclet/tagshandler/PackageTagsHandler.PackageSubstitution.html">
!
<code>&lt;packageSubstitution&gt;</code>
! </a>
element. For example, suppose we want all our value objecs generated
under the <code>example.valueobjects</code> package.
</p>
! <source><![CDATA[<valueobject>
<packageSubstitution packages="ejb" substituteWith="valueobjects"/>
! </valueobject>]]></source>
! <p>
This tells xdoclet to substitute all packages names ending in "ejb" with
a package name ending in "valueobject". The
***************
*** 336,340 ****
xdoclet subtasks, so it's a good thing to understand how to use it.
</p>
! <p>
Now, if you don't like the default naming pattern for value objects, you
can change it by setting the <code>pattern</code> attribute for the
--- 369,373 ----
xdoclet subtasks, so it's a good thing to understand how to use it.
</p>
! <p>
Now, if you don't like the default naming pattern for value objects, you
can change it by setting the <code>pattern</code> attribute for the
***************
*** 346,356 ****
declaration:
</p>
! <source><![CDATA[<valueobject pattern="{0}VO">
<packageSubstitution packages="ejb" substituteWith="valueobjects"/>
! </valueobject>]]>
! </source>
!
! <subsection name="Modifying the generated value object">
! <p>
XDoclet provides merge points in the value object template that you
can use to add custom code to the generated value objects. If you
--- 379,387 ----
declaration:
</p>
! <source><![CDATA[<valueobject pattern="{0}VO">
<packageSubstitution packages="ejb" substituteWith="valueobjects"/>
! </valueobject>]]></source>
! <subsection name="Modifying the generated value object">
! <p>
XDoclet provides merge points in the value object template that you
can use to add custom code to the generated value objects. If you
***************
*** 358,362 ****
about them now</a>.
</p>
! <p>
The merge point is just before the closing brace of the generated
class and is called <code>valueobject-custom.xdt</code>. Please note
--- 389,393 ----
about them now</a>.
</p>
! <p>
The merge point is just before the closing brace of the generated
class and is called <code>valueobject-custom.xdt</code>. Please note
***************
*** 369,374 ****
language.
</p>
! </subsection>
! </section>
! </body>
</document>
--- 400,405 ----
language.
</p>
! </subsection>
! </section>
! </body>
</document>
-------------------------------------------------------
This sf.net email is sponsored by:
With Great Power, Comes Great Responsibility
Learn to use your power at OSDN's High Performance Computing Channel
http://hpc.devchannel.org/
_______________________________________________
Xdoclet-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
