Revision as of 12:43, 5 May 2011

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

Weaving JPA Entities

How to Configure Static Weaving for JPA Entities

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 How to Configure Dynamic Weaving for JPA Entities Using the EclipseLink Agent).

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

Prior to weaving, your persistence unit should be set-up in a way that is understood by eclipselink. There are two basic configurations:

1. A jar file - setup as specified in the JPA specification

• classes stored at the base in directories based on their package structure
• a META-INF directory containing your persistence.xml. Note: Using the persistenceunitinfo setting below, you can avoid this requirement

e.g. mypersistenceunit.jar could contain

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

2. An exploded directory structure

• classes stored at the base in directories based on their package structure
• a META-INF directory containing your persistence.xml. Note: Using the persistenceunitinfo setting below, you can avoid this requirement

e.g. 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

To Configure Static Weaving for JPA Entities

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

        
        

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

      
      

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

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

About Weaving	About Weaving	Weaving POJO Classes
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...