je/docs/java/com/sleepycat/persist/model/ClassEnhancer.html
2021-06-06 13:46:45 -04:00

487 lines
20 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_151) on Tue Oct 31 17:36:46 EDT 2017 -->
<title>ClassEnhancer (Oracle - Berkeley DB Java Edition API)</title>
<meta name="date" content="2017-10-31">
<link rel="stylesheet" type="text/css" href="../../../../style.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="ClassEnhancer (Oracle - Berkeley DB Java Edition API)";
}
}
catch(err) {
}
//-->
var methods = {"i0":10,"i1":10,"i2":9,"i3":9,"i4":10,"i5":10};
var tabs = {65535:["t0","All Methods"],1:["t1","Static Methods"],2:["t2","Instance Methods"],8:["t4","Concrete Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/ClassEnhancer.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../com/sleepycat/persist/model/AnnotationModel.html" title="class in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/ClassEnhancerTask.html" title="class in com.sleepycat.persist.model"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?com/sleepycat/persist/model/ClassEnhancer.html" target="_top">Frames</a></li>
<li><a href="ClassEnhancer.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor.summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor.detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">com.sleepycat.persist.model</div>
<h2 title="Class ClassEnhancer" class="title">Class ClassEnhancer</h2>
</div>
<div class="contentContainer">
<ul class="inheritance">
<li>java.lang.Object</li>
<li>
<ul class="inheritance">
<li>com.sleepycat.persist.model.ClassEnhancer</li>
</ul>
</li>
</ul>
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Implemented Interfaces:</dt>
<dd>java.lang.instrument.ClassFileTransformer</dd>
</dl>
<hr>
<br>
<pre>public class <span class="typeNameLabel">ClassEnhancer</span>
extends java.lang.Object
implements java.lang.instrument.ClassFileTransformer</pre>
<div class="block">Enhances the bytecode of persistent classes to provide efficient access to
fields and constructors, and to avoid special security policy settings for
accessing non-public members. Classes are enhanced if they are annotated
with <a href="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><code>Entity</code></a> or <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a>.
<p><code>ClassEnhancer</code> objects are thread-safe. Multiple threads may
safely call the methods of a shared <code>ClassEnhancer</code> object.</p>
<p>As described in the <a
href="../package-summary.html#bytecode">package summary</a>, bytecode
enhancement may be used either at runtime or offline (at build time).</p>
<p>To use enhancement offline, this class may be used as a <a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#main-java.lang.String:A-"><code>main
program</code></a>.
<!-- begin JE only -->
It may also be used via an <a href="../../../../com/sleepycat/persist/model/ClassEnhancerTask.html" title="class in com.sleepycat.persist.model"><code>ant task</code></a>.
<!-- end JE only -->
</p>
<p>For enhancement at runtime, this class provides the low level support
needed to transform class bytes during class loading. To configure runtime
enhancement you may use one of the following approaches:</p>
<ol>
<li>The BDB <code>je-&lt;version&gt;.jar</code> or <code>db.jar</code> file may be used as
an instrumentation agent as follows:
<pre class="code">java -javaagent:&lt;BDB-JAR-FILE&gt;=enhance:packageNames ...</pre>
<code>packageNames</code> is a comma separated list of packages containing
persistent classes. Sub-packages of these packages are also searched. If
<code>packageNames</code> is omitted then all packages known to the current
classloader are searched.
<p>The "-v" option may be included in the comma separated list to print the
name of each class that is enhanced.</p></li>
<li>The <a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#enhance-java.lang.String-byte:A-"><code>enhance(java.lang.String, byte[])</code></a> method may be called to implement a class loader
that performs enhancement. Using this approach, it is the developer's
responsibility to implement and configure the class loader.</li>
</ol></div>
<dl>
<dt><span class="simpleTagLabel">Author:</span></dt>
<dd>Mark Hayes</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<ul class="blockList">
<li class="blockList"><a name="constructor.summary">
<!-- -->
</a>
<h3>Constructor Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Constructor Summary table, listing constructors, and an explanation">
<caption><span>Constructors</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colOne" scope="col">Constructor and Description</th>
</tr>
<tr class="altColor">
<td class="colOne"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#ClassEnhancer--">ClassEnhancer</a></span>()</code>
<div class="block">Creates a class enhancer that searches all packages.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colOne"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#ClassEnhancer-java.util.Set-">ClassEnhancer</a></span>(java.util.Set&lt;java.lang.String&gt;&nbsp;packageNames)</code>
<div class="block">Creates a class enhancer that searches a given set of packages.</div>
</td>
</tr>
</table>
</li>
</ul>
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t1" class="tableTab"><span><a href="javascript:show(1);">Static Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t4" class="tableTab"><span><a href="javascript:show(8);">Concrete Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code>byte[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#enhance-java.lang.String-byte:A-">enhance</a></span>(java.lang.String&nbsp;className,
byte[]&nbsp;classBytes)</code>
<div class="block">Enhances the given class bytes if the class is annotated with <a href="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><code>Entity</code></a> or <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a>.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#getVerbose--">getVerbose</a></span>()</code>
<div class="block">Gets verbose mode.</div>
</td>
</tr>
<tr id="i2" class="altColor">
<td class="colFirst"><code>static void</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#main-java.lang.String:A-">main</a></span>(java.lang.String[]&nbsp;args)</code>
<div class="block">Enhances classes in the directories specified.</div>
</td>
</tr>
<tr id="i3" class="rowColor">
<td class="colFirst"><code>static void</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#premain-java.lang.String-java.lang.instrument.Instrumentation-">premain</a></span>(java.lang.String&nbsp;args,
java.lang.instrument.Instrumentation&nbsp;inst)</code>
<div class="block">Enhances classes as specified by a JVM -javaagent argument.</div>
</td>
</tr>
<tr id="i4" class="altColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#setVerbose-boolean-">setVerbose</a></span>(boolean&nbsp;verbose)</code>
<div class="block">Sets verbose mode.</div>
</td>
</tr>
<tr id="i5" class="rowColor">
<td class="colFirst"><code>byte[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#transform-java.lang.ClassLoader-java.lang.String-java.lang.Class-java.security.ProtectionDomain-byte:A-">transform</a></span>(java.lang.ClassLoader&nbsp;loader,
java.lang.String&nbsp;className,
java.lang.Class&lt;?&gt;&nbsp;classBeingRedefined,
java.security.ProtectionDomain&nbsp;protectionDomain,
byte[]&nbsp;classfileBuffer)</code>&nbsp;</td>
</tr>
</table>
<ul class="blockList">
<li class="blockList"><a name="methods.inherited.from.class.java.lang.Object">
<!-- -->
</a>
<h3>Methods inherited from class&nbsp;java.lang.Object</h3>
<code>clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</code></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<ul class="blockList">
<li class="blockList"><a name="constructor.detail">
<!-- -->
</a>
<h3>Constructor Detail</h3>
<a name="ClassEnhancer--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>ClassEnhancer</h4>
<pre>public&nbsp;ClassEnhancer()</pre>
<div class="block">Creates a class enhancer that searches all packages.</div>
</li>
</ul>
<a name="ClassEnhancer-java.util.Set-">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>ClassEnhancer</h4>
<pre>public&nbsp;ClassEnhancer(java.util.Set&lt;java.lang.String&gt;&nbsp;packageNames)</pre>
<div class="block">Creates a class enhancer that searches a given set of packages.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>packageNames</code> - a set of packages to search for persistent
classes. Sub-packages of these packages are also searched. If empty or
null, all packages known to the current classloader are searched.</dd>
</dl>
</li>
</ul>
</li>
</ul>
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="main-java.lang.String:A-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>main</h4>
<pre>public static&nbsp;void&nbsp;main(java.lang.String[]&nbsp;args)
throws java.lang.Exception</pre>
<div class="block">Enhances classes in the directories specified. The class files are
replaced when they are enhanced, without changing the file modification
date. For example:
<pre class="code">java -cp je-&lt;version&gt;.jar com.sleepycat.persist.model.ClassEnhancer ./classes</pre>
<p>The "-v" argument may be specified to print the name of each class
file that is enhanced. The total number of class files enhanced will
always be printed.</p></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>args</code> - one or more directories containing classes to be enhanced.
Subdirectories of these directories will also be searched. Optionally,
-v may be included to print the name of every class file enhanced.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code>java.lang.Exception</code> - if a problem occurs.</dd>
</dl>
</li>
</ul>
<a name="premain-java.lang.String-java.lang.instrument.Instrumentation-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>premain</h4>
<pre>public static&nbsp;void&nbsp;premain(java.lang.String&nbsp;args,
java.lang.instrument.Instrumentation&nbsp;inst)</pre>
<div class="block">Enhances classes as specified by a JVM -javaagent argument.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>args</code> - see java.lang.instrument.Instrumentation.</dd>
<dd><code>inst</code> - see java.lang.instrument.Instrumentation.</dd>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><code>Instrumentation</code></dd>
</dl>
</li>
</ul>
<a name="setVerbose-boolean-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>setVerbose</h4>
<pre>public&nbsp;void&nbsp;setVerbose(boolean&nbsp;verbose)</pre>
<div class="block">Sets verbose mode.
<p>True may be specified to print the name of each class file that is
enhanced. This property is false by default.</p></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>verbose</code> - whether to use verbose mode.</dd>
</dl>
</li>
</ul>
<a name="getVerbose--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>getVerbose</h4>
<pre>public&nbsp;boolean&nbsp;getVerbose()</pre>
<div class="block">Gets verbose mode.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether to use verbose mode.</dd>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="../../../../com/sleepycat/persist/model/ClassEnhancer.html#setVerbose-boolean-"><code>setVerbose(boolean)</code></a></dd>
</dl>
</li>
</ul>
<a name="transform-java.lang.ClassLoader-java.lang.String-java.lang.Class-java.security.ProtectionDomain-byte:A-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>transform</h4>
<pre>public&nbsp;byte[]&nbsp;transform(java.lang.ClassLoader&nbsp;loader,
java.lang.String&nbsp;className,
java.lang.Class&lt;?&gt;&nbsp;classBeingRedefined,
java.security.ProtectionDomain&nbsp;protectionDomain,
byte[]&nbsp;classfileBuffer)</pre>
<dl>
<dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
<dd><code>transform</code>&nbsp;in interface&nbsp;<code>java.lang.instrument.ClassFileTransformer</code></dd>
</dl>
</li>
</ul>
<a name="enhance-java.lang.String-byte:A-">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>enhance</h4>
<pre>public&nbsp;byte[]&nbsp;enhance(java.lang.String&nbsp;className,
byte[]&nbsp;classBytes)</pre>
<div class="block">Enhances the given class bytes if the class is annotated with <a href="../../../../com/sleepycat/persist/model/Entity.html" title="annotation in com.sleepycat.persist.model"><code>Entity</code></a> or <a href="../../../../com/sleepycat/persist/model/Persistent.html" title="annotation in com.sleepycat.persist.model"><code>Persistent</code></a>.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>className</code> - the class name in binary format; for example,
"my.package.MyClass$Name", or null if no filtering by class name
should be performed.</dd>
<dd><code>classBytes</code> - are the class file bytes to be enhanced.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the enhanced bytes, or null if no enhancement was performed.</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/ClassEnhancer.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../com/sleepycat/persist/model/AnnotationModel.html" title="class in com.sleepycat.persist.model"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../com/sleepycat/persist/model/ClassEnhancerTask.html" title="class in com.sleepycat.persist.model"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?com/sleepycat/persist/model/ClassEnhancer.html" target="_top">Frames</a></li>
<li><a href="ClassEnhancer.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor.summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor.detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><font size=1>Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.</font> </small></p>
</body>
</html>