Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Revision as of 11:27, 6 May 2011

EclipseLink JPA

EclipseLink
Website
Download
Community
Mailing List • Forums • IRC • mattermost
Issues
Open • Help Wanted • Bug Day
Contribute
Browse Source

Configuring Static Weaving

Use this option to weave all applicable class files at build time so that you can deliver pre-woven class files. Consider this option to weave all applicable class files at build time so that you can deliver prewoven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving (see Configuring Dynamic Weaving).

In addition, consider using dynamic weaving to weave in Java environments where you cannot configure an agent.

Prerequisite: Persistence Unit Packaging

Prior to weaving, you must package your persistence unit in either of the following configurations:

JAR file, as specified in the JPA 2.0 specification.

For more information, see Section 11.1.18 "Persistence Unit Packaging" in the JPA Specification.

Exploded directory structure

In both cases, the requirements are:

Classes are stored at the base in directories based on their package structure
A META-INF directory that contains the persistence.xml file. Note: Using the persistenceunitinfo setting below, you can avoid this requirement.

For example, when using a JAR file, mypersitenceunit.jar could contain the following:

mypackage/MyEntity1.class
mypackage/MyEntity2.class
mypackage2/MyEntity3.class
META-INF/persistence.xml

For example, If your base directory was c:/classes, the exploded directory structure would look as follows:

c:/classes/mypackage/MyEntity1.class
c:/classes/mypackage/MyEntity2.class
c:/classes/mypackage2/MyEntity3.class
c:/classes/META-INF/persistence.xml

Step 1: Execute the Static Weaver

Execute the static static weaver in one of the following ways:

1. Use the weave ant task, as follows:

Configure the weave Ant task in your build script, as this example shows. The EclipseLink weave Ant Task Attributes table lists the attributes of this task.
EclipseLink weave Ant Task

<target name="define.task" description="New task definition for EclipseLink static weaving"/>

    <taskdef name="weave" classname="org.eclipse.persistence.tools.weaving.jpa.StaticWeaveAntTask"/>
</target>
<target name="weaving" description="perform weaving" depends="define.task">
    <weave  source="c:\myjar.jar"
            target="c:\wovenmyjar.jar"
            persistenceinfo="c:\myjar-containing-persistenceinfo.jar">
        <classpath>
            <pathelement path="c:\myjar-dependent.jar"/>
        </classpath>

    </weave>
</target>

EclipseLink weave Ant Task Attributes

Attribute	Description	Default	Required or Optional
`source`	Specifies the location of the Java source files to weave: either a directory or a JAR file. If the `persistence.xml` file is not in a META-INF directory at this location, you must specify the location of the `persistence.xml` using the `persistenceinfo` attribute.		Required
`target`	Specifies the output location: either a directory or a JAR file.		Required
`persistenceinfo`	Specifies the location of the `persistence.xml` file if it is not in the same location as the source. Note: persistence.xml should be put in a directory called META-INF at this location		Optional
`log`	Specifies a logging file.	See Logging.	Optional
`loglevel`	Specifies the amount and detail of log output. Valid `java.util.logging.Level` values are the following: `OFF` `SEVERE` `WARNING` `INFO` `CONFIG` `FINE` `FINER` `FINEST` For more information, see Logging.	`Level.OFF`	Optional

Note: If source and target point to the same location and, if the source is a directory (not a JAR file), EclipseLink will weave in place. If source and target point to different locations, or if the source is a JAR file (as the EclipseLink weave Ant Task example shows), EclipseLink cannot weave in place.

Configure the weave task with an appropriate <classpath> element, as the EclipseLink weave Ant Task example shows, so that EclipseLink can load all required source classes.
Execute the Ant task using the command line that this example shows.
In this example, the weave Ant task is in the build.xml file:
EclipseLink weave Ant Task Command Line
```
ant -lib C:\eclipselink.jar -f build.xml weave
```
Note: You must specify the eclipselink.jar file (the JAR that contains the EclipseLink weave Ant task) using the Ant command line -lib option instead of using the taskdef attribute classpath.

</li>

Use the command line as follows:

java org.eclipse.persistence.tools.weaving.jpa.StaticWeave [arguments] <source> <target>

The following example shows how to use the StaticWeave class on Windows systems. The EclipseLink StaticWeave Class Command Line Arguments table lists the arguments of this class.
Executing StaticWeave on the Command Line

java org.eclipse.persistence.tools.weaving.jpa.StaticWeave  -persistenceinfo c:\myjar-containing-persistencexml.jar 
-classpath c:\classpath1;c:\classpath2 c:\myjar-source.jar c:\myjar-target.jar

EclipseLink StaticWeave Class Command Line Arguments

Argument	Description	Default	Required or Optional
`-persistenceinfo`	Specifies the location of the `persistence.xml` file if it is not at the same location as the source (see `-classpath`) Note: EclipseLink will look in a META-INF directory at that location for persistence.xml.		Optional
`-classpath`	Specifies the location of the Java source files to weave: either a directory or a JAR file. For Windows systems, use delimiter `" ; "`, and for Unix, use delimiter `" : "`. If the `persistence.xml` file is not in this location, you must specify the location of the `persistence.xml` using the `-persistenceinfo` attribute.		Required
`-log`	Specifies a logging file.	See Logging.	Optional
`-loglevel`	Specifies the amount and detail of log output. Valid `java.util.logging.Level` values are as follows: `OFF` `SEVERE` `WARNING` `INFO` `CONFIG` `FINE` `FINER` `FINEST` For more information, see Logging.	`Level.OFF`	Optional
`<source>`	Specifies the location of the Java source files to weave: either a directory or a JAR file. If the `persistence.xml` file is not in this location, you must specify the location of the `persistence.xml` using the `-persistenceinfo` attribute.		Required
`<target>`	Specifies the output location: either a directory or a JAR file.		Required

Note: If <source> and <target> point to the same location and if the <source> is a directory (not a JAR file), EclipseLink will weave in place. If <source> and <target> point to different locations, or if the source is a JAR file (as the Executing StaticWeave on the Command Line example shows), EclipseLink cannot weave in place.

</ol>

</li>

Configure your persistence.xml file with a eclipselink.weaving extension set to static, as this example shows:
Setting eclipselink.weaving in the persistence.xml File

<persistence>
    <persistence-unit name="HumanResources">
        <class>com.acme.Employee</class>
        ...
        <properties>

            <property
                name="eclipselink.weaving"
                value="static"
            >
        </properties>
    </persistence-unit>
</persistence>

For more information, see the EclipseLink JPA Persistence Unit Properties for Customization and Validation table.

Package and deploy your application.
For more information, see Packaging and Deploying EclipseLink JPA Applications.

</ol>

Version: 2.2.0 DRAFT
Other versions...

Configuring Dynamic Weaving	About Weaving	Disabling Weaving with Persistence Unit Properties
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...

Categories:

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Static_Weaving&oldid=249742"

@@ Line 11: / Line 11: @@
 In addition, consider using dynamic weaving to weave in Java environments where you cannot configure an agent.
-Prior to weaving, you must configure your persistence unit to be understood by EclipseLink. There are two basic configurations:
+==Prerequisite: Persistence Unit Packaging==
+Prior to weaving, you must package your persistence unit in either of the following configurations:
 * JAR file, as specified in the JPA 2.0 specification.{{EclipseLink_Spec
@@ Line 36: / Line 37: @@
 * <tt>c:/classes/mypackage2/MyEntity3.class</tt>
 * <tt>c:/classes/META-INF/persistence.xml </tt>
+==Step 1: Execute the Static Weaver==
+Execute the static static weaver in one of the following ways:
+. Use the <tt>weave</tt> ant task, as follows:
+<ul>
+<li> Configure the <tt>weave</tt> Ant task in your build script, as this example shows. The [[#Table 19-31|EclipseLink weave Ant Task Attributes]] table lists the attributes of this task.<br>
+<span id="Example 19-37"></span>
+''''' EclipseLink weave Ant Task'''''
+<div class="pre">
+ <target name="define.task" description="New task definition for EclipseLink static weaving"/>
+     <taskdef name="weave" classname="org.eclipse.persistence.tools.weaving.jpa.StaticWeaveAntTask"/>
+ </target>
+ <target name="weaving" description="perform weaving" depends="define.task">
+     <weave  source="c:\myjar.jar"
+             target="c:\wovenmyjar.jar"
+             persistenceinfo="c:\myjar-containing-persistenceinfo.jar">
+         <classpath>
+             <pathelement path="c:\myjar-dependent.jar"/>
+         </classpath>
+     </weave>
+ </target>
+</div>
+<br>
+<span id="Table 19-31"></span>
+''''' EclipseLink <tt>weave</tt> Ant Task Attributes'''''
+{| class="RuleFormalMax" dir="ltr" title="EclipseLink weave Ant Task Attributes" summary="This table lists the attributes of the EclipseLink JPA weave Ant task." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+|- align="left" valign="top"
+! id="r1c1-t47" align="left" valign="bottom" | '''Attribute'''
+! id="r1c2-t47" align="left" valign="bottom" | '''Description'''
+! id="r1c3-t47" align="left" valign="bottom" | '''Default'''
+! id="r1c4-t47" align="left" valign="bottom" | '''Required or Optional'''
+|- align="left" valign="top"
+| id="r2c1-t47" headers="r1c1-t47" align="left" |
+<tt>source</tt>
+| headers="r2c1-t47 r1c2-t47" align="left" |
+Specifies the location of the Java source files to weave: either a directory or a JAR file.
+If the <tt>persistence.xml</tt> file is not in a META-INF directory at this location, you must specify the location of the <tt>persistence.xml</tt> using the <tt>persistenceinfo</tt> attribute.
+| headers="r2c1-t47 r1c3-t47" align="left" | <br>
+| headers="r2c1-t47 r1c4-t47" align="left" |
+Required
+|- align="left" valign="top"
+| id="r3c1-t47" headers="r1c1-t47" align="left" |
+<tt>target</tt>
+| headers="r3c1-t47 r1c2-t47" align="left" |
+Specifies the output location: either a directory or a JAR file.
+| headers="r3c1-t47 r1c3-t47" align="left" | <br>
+| headers="r3c1-t47 r1c4-t47" align="left" |
+Required
+|- align="left" valign="top"
+| id="r4c1-t47" headers="r1c1-t47" align="left" |
+<tt>persistenceinfo</tt>
+| headers="r4c1-t47 r1c2-t47" align="left" |
+Specifies the location of the <tt>persistence.xml</tt> file if it is not in the same location as the source.  Note: persistence.xml should be put in a directory called META-INF at this location
+| headers="r4c1-t47 r1c3-t47" align="left" | <br>
+| headers="r4c1-t47 r1c4-t47" align="left" |
+Optional
+|- align="left" valign="top"
+| id="r5c1-t47" headers="r1c1-t47" align="left" |
+<tt>log</tt>
+| headers="r5c1-t47 r1c2-t47" align="left" |
+Specifies a logging file.
+| headers="r5c1-t47 r1c3-t47" align="left" |
+See [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+| headers="r5c1-t47 r1c4-t47" align="left" |
+Optional
+|- align="left" valign="top"
+| id="r6c1-t47" headers="r1c1-t47" align="left" |
+<tt>loglevel</tt>
+| headers="r6c1-t47 r1c2-t47" align="left" |
+Specifies the amount and detail of log output.
+Valid <tt>java.util.logging.Level</tt> values are the following:
+* <tt>OFF</tt>
+* <tt>SEVERE</tt>
+* <tt>WARNING</tt>
+* <tt>INFO</tt>
+* <tt>CONFIG</tt>
+* <tt>FINE</tt>
+* <tt>FINER</tt>
+* <tt>FINEST</tt>
+For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+| headers="r6c1-t47 r1c3-t47" align="left" |
+<tt>Level.OFF</tt>
+| headers="r6c1-t47 r1c4-t47" align="left" |
+Optional
+|}
+<br><br>
+{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+| align="left" |
+'''Note:''' If <tt>source</tt> and <tt>target</tt> point to the same location and, if the <tt>source</tt> is a directory (not a JAR file), EclipseLink will weave in place. If <tt>source</tt> and <tt>target</tt> point to different locations, or if the <tt>source</tt> is a JAR file (as the [[#Example 19-37|EclipseLink weave Ant Task]] example shows), EclipseLink cannot weave in place.
+|}
+<br></li>
+<li> Configure the <tt>weave</tt> task with an appropriate <tt><classpath></tt> element, as the [[#Example 19-37|EclipseLink weave Ant Task]] example shows, so that EclipseLink can load all required source classes.</li>
+<li> Execute the Ant task using the command line that this example shows.<br>In this example, the <tt>weave</tt> Ant task is in the <tt>build.xml</tt> file:<br>
+<span id="Example 19-38"></span>
+''''' EclipseLink weave Ant Task Command Line'''''
+<div class="pre">
+ ant -lib C:\eclipselink.jar -f build.xml weave
+</div>
+{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+| align="left" |
+'''Note:''' You must specify the <tt>eclipselink.jar</tt> file (the JAR that contains the EclipseLink <tt>weave</tt> Ant task) using the Ant command line <tt>-lib</tt> option instead of using the <tt>taskdef</tt> attribute <tt>classpath</tt>.
+|}
+<br>
+</li></ul>
+</li>
+<li>Use the command line as follows: <br>
+<div class="pre">
+<tt><nowiki> java org.eclipse.persistence.tools.weaving.jpa.StaticWeave [arguments] <source> <target></nowiki></tt>
+ </div>
+<br>The following example shows how to use the <tt>StaticWeave</tt> class on Windows systems. The [[#Table 19-32|EclipseLink StaticWeave Class Command Line Arguments]] table lists the arguments of this class.<br>
+<span id="Example 19-39"></span>
+''''' Executing StaticWeave on the Command Line'''''
+<div class="pre">
+ java org.eclipse.persistence.tools.weaving.jpa.StaticWeave  -persistenceinfo c:\myjar-containing-persistencexml.jar
+ -classpath c:\classpath1;c:\classpath2 c:\myjar-source.jar c:\myjar-target.jar
+</div>
+<br>
+<span id="Table 19-32"></span>
+''''' EclipseLink StaticWeave Class Command Line Arguments'''''
+{| class="RuleFormalMax" dir="ltr" title="EclipseLink StaticWeave Class Command Line Arguments" summary="This table lists the arguments of the EclipseLink JPA StaticWeave class." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
+|- align="left" valign="top"
+! id="r1c1-t50" align="left" valign="bottom" | '''Argument'''
+! id="r1c2-t50" align="left" valign="bottom" | '''Description'''
+! id="r1c3-t50" align="left" valign="bottom" | '''Default'''
+! id="r1c4-t50" align="left" valign="bottom" | '''Required or Optional'''
+|- align="left" valign="top"
+| id="r2c1-t50" headers="r1c1-t50" align="left" |
+<tt>-persistenceinfo</tt>
+| headers="r2c1-t50 r1c2-t50" align="left" |
+Specifies the location of the <tt>persistence.xml</tt> file if it is not at the same location as the source (see <tt>-classpath</tt>) Note: EclipseLink will look in a META-INF directory at that location for persistence.xml.
+| headers="r2c1-t50 r1c3-t50" align="left" | <br>
+| headers="r2c1-t50 r1c4-t50" align="left" |
+Optional
+|- align="left" valign="top"
+| id="r3c1-t50" headers="r1c1-t50" align="left" |
+<tt>-classpath</tt>
+| headers="r3c1-t50 r1c2-t50" align="left" |
+Specifies the location of the Java source files to weave: either a directory or a JAR file. For Windows systems, use delimiter <tt>" ; "</tt>, and for Unix, use delimiter <tt>" : "</tt>.
+If the <tt>persistence.xml</tt> file is not in this location, you must specify the location of the <tt>persistence.xml</tt> using the <tt>-persistenceinfo</tt> attribute.
+| headers="r3c1-t50 r1c3-t50" align="left" | <br>
+| headers="r3c1-t50 r1c4-t50" align="left" |
+Required
+|- align="left" valign="top"
+| id="r4c1-t50" headers="r1c1-t50" align="left" |
+<tt>-log</tt>
+| headers="r4c1-t50 r1c2-t50" align="left" |
+Specifies a logging file.
+| headers="r4c1-t50 r1c3-t50" align="left" |
+See [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+| headers="r4c1-t50 r1c4-t50" align="left" |
+Optional
+|- align="left" valign="top"
+| id="r5c1-t50" headers="r1c1-t50" align="left" |
+<tt>-loglevel</tt>
+| headers="r5c1-t50 r1c2-t50" align="left" |
+Specifies the amount and detail of log output.
+Valid <tt>java.util.logging.Level</tt> values are as follows:
+* <tt>OFF</tt>
+* <tt>SEVERE</tt>
+* <tt>WARNING</tt>
+* <tt>INFO</tt>
+* <tt>CONFIG</tt>
+* <tt>FINE</tt>
+* <tt>FINER</tt>
+* <tt>FINEST</tt>
+For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+| headers="r5c1-t50 r1c3-t50" align="left" |
+<tt>Level.OFF</tt>
+| headers="r5c1-t50 r1c4-t50" align="left" |
+Optional
+|- align="left" valign="top"
+| id="r6c1-t50" headers="r1c1-t50" align="left" |
+<tt><nowiki><source></nowiki></tt>
+| headers="r6c1-t50 r1c2-t50" align="left" |
+Specifies the location of the Java source files to weave: either a directory or a JAR file.
+If the <tt>persistence.xml</tt> file is not in this location, you must specify the location of the <tt>persistence.xml</tt> using the [[#-persistenceinfo|<tt>-persistenceinfo</tt>]] attribute.
+| headers="r6c1-t50 r1c3-t50" align="left" | <br>
+| headers="r6c1-t50 r1c4-t50" align="left" |
+Required
+|- align="left" valign="top"
+| id="r7c1-t50" headers="r1c1-t50" align="left" |
+<tt><target></tt>
+| headers="r7c1-t50 r1c2-t50" align="left" |
+Specifies the output location: either a directory or a JAR file.
+| headers="r7c1-t50 r1c3-t50" align="left" | <br>
+| headers="r7c1-t50 r1c4-t50" align="left" |
+Required
+|}
+<br><br>
+{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
+| align="left" |
+'''Note:''' If <tt><nowiki><source></nowiki></tt> and <tt><target></tt> point to the same location and if the <tt><nowiki><source></nowiki></tt> is a directory (not a JAR file), EclipseLink will weave in place. If <tt><nowiki><source></nowiki></tt> and <tt><target></tt> point to different locations, or if the <tt>source</tt> is a JAR file (as the [[#Example 19-39| Executing StaticWeave on the Command Line]] example shows), EclipseLink cannot weave in place.
+|}
+<br>
+</li></ol>
+</li>
+<li> Configure your <tt>persistence.xml</tt> file with a <tt>[[#eclipselink.weaving|eclipselink.weaving]]</tt> extension set to <tt>static</tt>, as this example shows:<br>
+<span id="Example 19-40"></span>
+''''' Setting eclipselink.weaving in the persistence.xml File'''''
+<div class="pre">
+ <persistence>
+     <persistence-unit name="HumanResources">
+         <class>com.acme.Employee</class>
+         ...
+         <properties>
+             <property
+                 name="eclipselink.weaving"
+                 value="static"
+             >
+         </properties>
+     </persistence-unit>
+ </persistence>
+</div>
+<br>
+For more information, see the [[#Table 19-16|EclipseLink JPA Persistence Unit Properties for Customization and Validation]] table.
+</li>
+<li>Package and deploy your application.<br>For more information, see [[Packaging%20and%20Deploying%20EclipseLink%20JPA%20Applications%20(ELUG)#Packaging and Deploying EclipseLink JPA Applications|Packaging and Deploying EclipseLink JPA Applications]].
+</li>
+</ol>
 {{EclipseLink_JPA

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "EclipseLink/UserGuide/JPA/Advanced JPA Development/Performance/Weaving/Static Weaving"

Revision as of 11:27, 6 May 2011

Configuring Static Weaving

Prerequisite: Persistence Unit Packaging

Step 1: Execute the Static Weaver