1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
/*
* Copyright (c) OSGi Alliance (2010, 2012). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.framework.hooks.weaving;
import java.security.ProtectionDomain;
import java.util.List;
import org.osgi.framework.wiring.BundleWiring;
/**
* A class being woven.
*
* This object represents a class being woven and is passed to each
* {@link WeavingHook} for possible modification. It allows access to the most
* recently transformed class file bytes and to any additional packages that
* should be added to the bundle as dynamic imports.
*
* <p>
* After weaving is {@link #isWeavingComplete() complete}, this object becomes
* effectively immutable.
*
* @NotThreadSafe
* @noimplement
* @version $Id: 549caef41027c8f0d0fdb4deae756eae6b69d1ee $
*/
public interface WovenClass {
/**
* Returns the class file bytes to be used to define the
* {@link WovenClass#getClassName() named} class.
*
* <p>
* While weaving is not {@link #isWeavingComplete() complete}, this method
* returns a reference to the class files byte array contained in this
* object. After weaving is {@link #isWeavingComplete() complete}, this
* object becomes effectively immutable and a copy of the class file byte
* array is returned.
*
* @return The bytes to be used to define the
* {@link WovenClass#getClassName() named} class.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[bundle,WEAVE]} and the Java runtime
* environment supports permissions.
*/
public byte[] getBytes();
/**
* Set the class file bytes to be used to define the
* {@link WovenClass#getClassName() named} class. This method must not be
* called outside invocations of the {@link WeavingHook#weave(WovenClass)
* weave} method by the framework.
*
* <p>
* While weaving is not {@link #isWeavingComplete() complete}, this method
* replaces the reference to the array contained in this object with the
* specified array. After weaving is {@link #isWeavingComplete() complete},
* this object becomes effectively immutable and this method will throw an
* {@link IllegalStateException}.
*
* @param newBytes The new classfile that will be used to define the
* {@link WovenClass#getClassName() named} class. The specified array
* is retained by this object and the caller must not modify the
* specified array.
* @throws NullPointerException If newBytes is {@code null}.
* @throws IllegalStateException If weaving is {@link #isWeavingComplete()
* complete}.
* @throws SecurityException If the caller does not have
* {@code AdminPermission[bundle,WEAVE]} and the Java runtime
* environment supports permissions.
*/
public void setBytes(byte[] newBytes);
/**
* Returns the list of dynamic import package descriptions to add to the
* {@link #getBundleWiring() bundle wiring} for this woven class. Changes
* made to the returned list will be visible to later {@link WeavingHook
* weaving hooks} called with this object. The returned list must not be
* modified outside invocations of the {@link WeavingHook#weave(WovenClass)
* weave} method by the framework.
*
* <p>
* After weaving is {@link #isWeavingComplete() complete}, this object
* becomes effectively immutable and the returned list will be unmodifiable.
*
* <p>
* If the Java runtime environment supports permissions, the caller must
* have {@code AdminPermission[bundle,WEAVE]} to modify the returned list.
*
* @return A list containing zero or more dynamic import package
* descriptions to add to the bundle wiring for this woven class.
* This list must throw {@code IllegalArgumentException} if a
* malformed dynamic import package description is added.
* @see "Core Specification, Dynamic Import Package, for the syntax of a dynamic import package description."
*/
public List<String> getDynamicImports();
/**
* Returns whether weaving is complete in this woven class. Weaving is
* complete after the last {@link WeavingHook weaving hook} is called and
* the class is defined.
*
* <p>
* After weaving is complete, this object becomes effectively immutable.
*
* @return {@code true} weaving is complete, {@code false} otherwise.
*/
public boolean isWeavingComplete();
/**
* Returns the fully qualified name of the class being woven.
*
* @return The fully qualified name of the class being woven.
*/
public String getClassName();
/**
* Returns the protection domain to which the woven class will be assigned
* when it is defined.
*
* @return The protection domain to which the woven class will be assigned
* when it is defined, or {@code null} if no protection domain will
* be assigned.
*/
public ProtectionDomain getProtectionDomain();
/**
* Returns the class defined by this woven class. During weaving, this
* method will return {@code null}. Once weaving is
* {@link #isWeavingComplete() complete}, this method will return the class
* object if this woven class was used to define the class.
*
* @return The class associated with this woven class, or {@code null} if
* weaving is not complete, the class definition failed or this
* woven class was not used to define the class.
*/
public Class<?> getDefinedClass();
/**
* Returns the bundle wiring whose class loader will define the woven class.
*
* @return The bundle wiring whose class loader will define the woven class.
*/
public BundleWiring getBundleWiring();
}
|
