Jump to: navigation, search

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

m
m (Use the Maven plugin)
 
(15 intermediate revisions by 4 users not shown)
Line 7: Line 7:
 
=Configuring Static Weaving=
 
=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 [[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Dynamic Weaving|Configuring Dynamic Weaving]]).
+
Use static weaving 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 [[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Dynamic Weaving|Configuring Dynamic Weaving]]).
  
In addition, consider using dynamic weaving to weave in Java environments where you cannot configure an agent.
+
In addition, consider using static weaving to weave in Java environments where you cannot configure an agent.
  
==Prerequisite: Persistence Unit Packaging==
+
==Prerequisite: Organize/Package Files==
 
Prior to weaving, you must package your persistence unit in either of the following configurations:  
 
Prior to weaving, you must package your persistence unit in either of the following configurations:  
  
Line 22: Line 22:
 
In both cases, the requirements are:
 
In both cases, the requirements are:
  
* Classes are stored at the base in directories based on their package structure  
+
* Classes must be stored at the base in directories based on their package structure  
* A <tt>META-INF</tt> directory that contains the <tt>persistence.xml</tt> file. Note: Using the <tt>persistenceunitinfo</tt> setting below, you can avoid this requirement.
+
* There must be a <tt>META-INF</tt> directory that contains the <tt>persistence.xml</tt> file. <br/>Note: You can use the <tt>persistenceinfo</tt> setting on the <tt>weave</tt> Ant task, as described in the [[#Table 19-31|EclipseLink weave Ant Task Attributes]] table, below, to specify a different location.
  
 
For example, when using a JAR file, <tt>mypersitenceunit.jar</tt> could contain the following:
 
For example, when using a JAR file, <tt>mypersitenceunit.jar</tt> could contain the following:
Line 31: Line 31:
 
* <tt>META-INF/persistence.xml </tt>
 
* <tt>META-INF/persistence.xml </tt>
  
For example, If your base directory was c:/classes, the exploded directory structure would look as follows:
+
For example, If your base directory is c:/classes, the exploded directory structure would look as follows:
  
 
* <tt>c:/classes/mypackage/MyEntity1.class</tt>
 
* <tt>c:/classes/mypackage/MyEntity1.class</tt>
Line 40: Line 40:
 
==Step 1: Execute the Static Weaver==
 
==Step 1: Execute the Static Weaver==
  
Execute the static static weaver in one of the following ways:  
+
Execute the static weaver in one of the following ways:  
  
1. Use the <tt>weave</tt> ant task, as follows:
+
* [[#Use the weave Ant Task|Use the weave Ant Task]]
 +
* [[#Use the Maven plugin|Use the Maven plugin]]
 +
* [[#Use the Command Line|Use the Command Line]]
  
<ul>
+
===Use the weave Ant Task===
 +
Use the <tt>weave</tt> ant task, as follows:
 +
 
 +
<ol>
 
<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>
 
<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>
 
<span id="Example 19-37"></span>
 
''''' EclipseLink weave Ant Task'''''  
 
''''' EclipseLink weave Ant Task'''''  
 
<div class="pre">
 
<div class="pre">
  <target name="define.task" description="New task definition for EclipseLink static weaving"/>
+
  <target name="define.task" description="New task definition for EclipseLink static weaving">  
+
 
     <taskdef name="weave" classname="org.eclipse.persistence.tools.weaving.jpa.StaticWeaveAntTask"/>
 
     <taskdef name="weave" classname="org.eclipse.persistence.tools.weaving.jpa.StaticWeaveAntTask"/>
 
  </target>
 
  </target>
Line 105: Line 109:
 
Specifies a logging file.
 
Specifies a logging file.
 
| headers="r5c1-t47 r1c3-t47" align="left" |
 
| headers="r5c1-t47 r1c3-t47" align="left" |
See [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+
 
 
| headers="r5c1-t47 r1c4-t47" align="left" |
 
| headers="r5c1-t47 r1c4-t47" align="left" |
 
Optional
 
Optional
Line 123: Line 127:
 
* <tt>FINER</tt>
 
* <tt>FINER</tt>
 
* <tt>FINEST</tt>
 
* <tt>FINEST</tt>
 +
* <tt>ALL</tt>
  
 
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
 
For more information, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
Line 142: Line 147:
 
''''' EclipseLink weave Ant Task Command Line'''''  
 
''''' EclipseLink weave Ant Task Command Line'''''  
 
<div class="pre">
 
<div class="pre">
  ant -lib C:\eclipselink.jar -f build.xml weave
+
  ant -lib .\eclipselink.jar -lib .\persistence.jar -f build.xml weave
 
</div>
 
</div>
  
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 
| align="left" |
 
| 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>.
+
'''Note:''' You must specify the <tt>eclipselink.jar</tt> and <tt>persistence.jar</tt> files (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>
 
<br>
</li></ul>
+
</li></ol>
</li>
+
 
<li>Use the command line as follows: <br>
+
===Use the Maven plugin===
 +
If you are using Maven as build service there are two Maven plugins available.
 +
 
 +
For EclipseLink < 2.5.1 use [https://code.google.com/p/eclipselink-staticweave-maven-plugin/ original plugin.]
 +
 
 +
If you are using EclipseLink 2.5.1 or newer or you want to use Java 7 or newer there is an updated alternative available in [https://github.com/empulse-gmbh/eclipselink-static-weave-plugin GitHub]. Compiled versions are provided in Maven central.
 +
 
 +
Just add the plugin to your pom.xml.
 +
<div class="pre">
 +
<build>
 +
  ...
 +
  <plugins>
 +
    ...
 +
            <plugin>
 +
                <groupId>de.empulse.eclipselink</groupId>
 +
                <artifactId>staticweave-maven-plugin</artifactId>
 +
                <version>1.0.0</version>
 +
                <executions>
 +
                    <execution>
 +
                        <phase>process-classes</phase>
 +
                        <goals>
 +
                            <goal>weave</goal>
 +
                        </goals>
 +
                        <configuration>
 +
                            <persistenceXMLLocation>META-INF/persistence.xml</persistenceXMLLocation>
 +
                            <logLevel>FINE</logLevel>
 +
                        </configuration>
 +
                    </execution>
 +
                </executions>
 +
                <dependencies>
 +
                    <dependency>
 +
                        <groupId>org.eclipse.persistence</groupId>
 +
                        <artifactId>org.eclipse.persistence.jpa</artifactId>
 +
                        <version>${eclipselink.version}</version>
 +
                    </dependency>
 +
                </dependencies>
 +
            </plugin>
 +
        ...
 +
    </plugins>
 +
    ...
 +
</build>
 +
</div>
 +
 
 +
Replace
 +
<div class="pre>
 +
${eclipselink.version}
 +
</div>
 +
with the EclipseLink version you use in your project.
 +
 
 +
If you are using Eclipse as your IDE ensure m2e executes the plugin, otherwise weaving is not available in JUnit Tests.
 +
 
 +
Please follow the usage instructions given in the Git Repository for further configuration options.
 +
 
 +
===Use the Command Line===
 +
Use the command line as follows:  
 
<div class="pre">
 
<div class="pre">
 
<tt><nowiki> java org.eclipse.persistence.tools.weaving.jpa.StaticWeave [arguments] <source> <target></nowiki></tt>
 
<tt><nowiki> java org.eclipse.persistence.tools.weaving.jpa.StaticWeave [arguments] <source> <target></nowiki></tt>
Line 199: Line 258:
 
Specifies a logging file.
 
Specifies a logging file.
 
| headers="r4c1-t50 r1c3-t50" align="left" |
 
| headers="r4c1-t50 r1c3-t50" align="left" |
See [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Logging|Logging]].
+
 
 
| headers="r4c1-t50 r1c4-t50" align="left" |
 
| headers="r4c1-t50 r1c4-t50" align="left" |
 
Optional
 
Optional
Line 248: Line 307:
 
|}
 
|}
 
<br>
 
<br>
</li></ol>
+
 
</li>
+
===Step 2: Configure persitence.xml===
<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>
+
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>
 
<span id="Example 19-40"></span>
Line 272: Line 331:
 
<br>
 
<br>
 
For more information, see the [[#Table 19-16|EclipseLink JPA Persistence Unit Properties for Customization and Validation]] table.
 
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>
+
===Step 3: Package and Deploy===
</ol>
+
 
 +
Package and deploy your application.
 +
 
 +
 
  
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
 
|previous=[[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Dynamic Weaving|Configuring Dynamic Weaving]]
 
|previous=[[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Dynamic Weaving|Configuring Dynamic Weaving]]
|next    =[[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Disabling Weaving with Persistence Unit Properties|Disabling Weaving with Persistence Unit Properties]]
+
|next    =[[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/Weaving_POJO_Classes|Weaving POJO Classes]]
|up      =[[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving/About Weaving|About Weaving]]
+
|up      =[[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Performance/Weaving|Weaving]]
 
|version=2.2.0 DRAFT}}
 
|version=2.2.0 DRAFT}}

Latest revision as of 04:02, 26 May 2014

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source


Configuring Static Weaving

Use static weaving 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 static weaving to weave in Java environments where you cannot configure an agent.

Prerequisite: Organize/Package Files

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.
Elug javaspec icon.gif

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 must be stored at the base in directories based on their package structure
  • There must be a META-INF directory that contains the persistence.xml file.
    Note: You can use the persistenceinfo setting on the weave Ant task, as described in the EclipseLink weave Ant Task Attributes table, below, to specify a different location.

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 is 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 weaver in one of the following ways:

Use the weave Ant Task

Use the weave ant task, as follows:

  1. 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.

    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
    • ALL

    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.


  2. 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.
  3. 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 .\eclipselink.jar -lib .\persistence.jar -f build.xml weave
    

    Note: You must specify the eclipselink.jar and persistence.jar files (the JAR that contains the EclipseLink weave Ant task) using the Ant command line -lib option instead of using the taskdef attribute classpath.


Use the Maven plugin

If you are using Maven as build service there are two Maven plugins available.

For EclipseLink < 2.5.1 use original plugin.

If you are using EclipseLink 2.5.1 or newer or you want to use Java 7 or newer there is an updated alternative available in GitHub. Compiled versions are provided in Maven central.

Just add the plugin to your pom.xml.

<build>
 ...
  <plugins>
    ...
            <plugin>
               <groupId>de.empulse.eclipselink</groupId>
               <artifactId>staticweave-maven-plugin</artifactId>
               <version>1.0.0</version>
               <executions>
                   <execution>
                       <phase>process-classes</phase>
                       <goals>
                           <goal>weave</goal>
                       </goals>
                       <configuration>
                           <persistenceXMLLocation>META-INF/persistence.xml</persistenceXMLLocation>
                           <logLevel>FINE</logLevel>
                       </configuration>
                   </execution>
               </executions>
               <dependencies>
                   <dependency>
                       <groupId>org.eclipse.persistence</groupId>
                       <artifactId>org.eclipse.persistence.jpa</artifactId>
                       <version>${eclipselink.version}</version>
                   </dependency>
               </dependencies>
           </plugin>
        ...
   </plugins>
   ...
</build>

Replace

${eclipselink.version}

with the EclipseLink version you use in your project.

If you are using Eclipse as your IDE ensure m2e executes the plugin, otherwise weaving is not available in JUnit Tests.

Please follow the usage instructions given in the Git Repository for further configuration options.

Use the Command Line

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.

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.


Step 2: Configure persitence.xml

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.


Step 3: Package and Deploy

Package and deploy your application.



Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...