|
1 | 1 | /* |
2 | | - * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved. |
| 2 | + * Copyright (c) 2022, 2025, Oracle and/or its affiliates. All rights reserved. |
3 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 | 4 | * |
5 | 5 | * This code is free software; you can redistribute it and/or modify it |
|
30 | 30 | import jdk.internal.classfile.impl.AccessFlagsImpl; |
31 | 31 |
|
32 | 32 | /** |
33 | | - * Models the access flags for a class, method, or field. Delivered as a |
34 | | - * {@link ClassElement}, {@link FieldElement}, or {@link MethodElement} |
35 | | - * when traversing the corresponding model type. |
| 33 | + * Models the access flags for a class, method, or field. The access flags |
| 34 | + * appears exactly once in each class, method, or field; a {@link |
| 35 | + * ClassBuilder} and a {@link FieldBuilder} chooses an unspecified default value |
| 36 | + * if access flags are not provided, and a {@link MethodBuilder} is always |
| 37 | + * created with access flags. |
| 38 | + * <p> |
| 39 | + * {@code AccessFlags} cannot be created via a factory method directly; it can |
| 40 | + * be created with {@code withFlags} methods on the respective builders. |
| 41 | + * <p> |
| 42 | + * A {@link MethodBuilder} throws an {@link IllegalArgumentException} if it is |
| 43 | + * supplied an {@code AccessFlags} object that changes the preexisting |
| 44 | + * {@link ClassFile#ACC_STATIC ACC_STATIC} flag of the builder, because the |
| 45 | + * access flag change may invalidate previously supplied data to the builder. |
36 | 46 | * |
| 47 | + * @apiNote |
| 48 | + * The access flags of classes, methods, and fields are modeled as a standalone |
| 49 | + * object to support streaming as elements for {@link ClassFileTransform}. |
| 50 | + * Other access flags are not elements of a {@link CompoundElement} and thus not |
| 51 | + * modeled by {@code AccessFlags}; they provide their own {@code flagsMask}, |
| 52 | + * {@code flags}, and {@code has} methods. |
| 53 | + * |
| 54 | + * @see ClassModel#flags() |
| 55 | + * @see FieldModel#flags() |
| 56 | + * @see MethodModel#flags() |
| 57 | + * @see ClassBuilder#withFlags |
| 58 | + * @see FieldBuilder#withFlags |
| 59 | + * @see MethodBuilder#withFlags |
37 | 60 | * @since 24 |
38 | 61 | */ |
39 | 62 | public sealed interface AccessFlags |
40 | 63 | extends ClassElement, MethodElement, FieldElement |
41 | 64 | permits AccessFlagsImpl { |
42 | 65 |
|
43 | 66 | /** |
44 | | - * {@return the access flags, as a bit mask} |
| 67 | + * {@return the access flags, as a bit mask} It is in the range of unsigned |
| 68 | + * short, {@code [0, 0xFFFF]}. |
45 | 69 | */ |
46 | 70 | int flagsMask(); |
47 | 71 |
|
48 | 72 | /** |
49 | | - * {@return the access flags} |
| 73 | + * {@return the access flags, as a set of flag enums} |
| 74 | + * |
| 75 | + * @throws IllegalArgumentException if the flags mask has any undefined bit set |
| 76 | + * @see #location() |
50 | 77 | */ |
51 | 78 | Set<AccessFlag> flags(); |
52 | 79 |
|
53 | 80 | /** |
54 | | - * {@return whether the specified flag is present} The specified flag |
55 | | - * should be a valid flag for the classfile location associated with this |
56 | | - * element otherwise false is returned. |
| 81 | + * {@return whether the specified flag is set} If the specified flag |
| 82 | + * is not available to this {@linkplain #location() location}, returns |
| 83 | + * {@code false}. |
| 84 | + * |
57 | 85 | * @param flag the flag to test |
| 86 | + * @see #location() |
58 | 87 | */ |
59 | 88 | boolean has(AccessFlag flag); |
60 | 89 |
|
61 | 90 | /** |
62 | | - * {@return the classfile location for this element, which is either class, |
63 | | - * method, or field} |
| 91 | + * {@return the {@code class} file location for this element, which is |
| 92 | + * either class, method, or field} |
| 93 | + * |
| 94 | + * @see AccessFlag.Location#CLASS |
| 95 | + * @see AccessFlag.Location#FIELD |
| 96 | + * @see AccessFlag.Location#METHOD |
64 | 97 | */ |
65 | 98 | AccessFlag.Location location(); |
66 | 99 | } |
0 commit comments