View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.jdi.request;
27  
28  import com.sun.jdi.*;
29  
30  /**
31   * Request for notification when a class is prepared in the target VM.
32   * When an enabled ClassPrepareRequest is satisfied, an
33   * {@link com.sun.jdi.event.EventSet event set} containing a
34   * {@link com.sun.jdi.event.ClassPrepareEvent ClassPrepareEvent}
35   * will be placed on the
36   * {@link com.sun.jdi.event.EventQueue EventQueue}.
37   * The collection of existing ClassPrepareRequests is
38   * managed by the {@link EventRequestManager}
39   * <p>
40   * Class preparation is defined in the Java Virtual Machine
41   * Specification.
42   *
43   * @see com.sun.jdi.event.ClassPrepareEvent
44   * @see com.sun.jdi.event.EventQueue
45   * @see EventRequestManager
46   *
47   * @author Robert Field
48   * @since  1.3
49   */
50  @jdk.Exported
51  public interface ClassPrepareRequest extends EventRequest {
52  
53      /**
54       * Restricts the events generated by this request to be the
55       * preparation of the given reference type and any subtypes.
56       * An event will be generated for any prepared reference type that can
57       * be safely cast to the given reference type.
58       *
59       * @param refType the reference type to filter on.
60       * @throws InvalidRequestStateException if this request is currently
61       * enabled or has been deleted.
62       * Filters may be added only to disabled requests.
63       */
64      void addClassFilter(ReferenceType refType);
65  
66      /**
67       * Restricts the events generated by this request to the
68       * preparation of reference types whose name matches this restricted
69       * regular expression. Regular expressions are limited
70       * to exact matches and patterns that begin with '*' or end with '*';
71       * for example, "*.Foo" or "java.*".
72       *
73       * @param classPattern the pattern String to filter for.
74       * @throws InvalidRequestStateException if this request is currently
75       * enabled or has been deleted.
76       * Filters may be added only to disabled requests.
77       */
78      void addClassFilter(String classPattern);
79  
80      /**
81       * Restricts the events generated by this request to the
82       * preparation of reference types whose name does <b>not</b> match
83       * this restricted regular expression. Regular expressions are limited
84       * to exact matches and patterns that begin with '*' or end with '*';
85       * for example, "*.Foo" or "java.*".
86       *
87       * @param classPattern the pattern String to filter against.
88       * @throws InvalidRequestStateException if this request is currently
89       * enabled or has been deleted.
90       * Filters may be added only to disabled requests.
91       */
92      void addClassExclusionFilter(String classPattern);
93  
94      /**
95       * Restricts the events generated by this request to the
96       * preparation of reference types for which the restricted regular
97       * expression 'sourceNamePattern' matches one of the 'sourceNames' for
98       * the reference type being prepared.
99       * That is, if refType is the ReferenceType being prepared,
100      * then there exists at least one stratum, call it 'someStratum'
101      * on the list returned by
102      *     refType.availableStrata();
103      *
104      * such that a name on the list returned by
105      *     refType.sourceNames(someStratam)
106      *
107      * matches 'sourceNamePattern'.
108      * Regular expressions are limited
109      * to exact matches and patterns that begin with '*' or end with '*';
110      * for example, "*.Foo" or "java.*".
111      * <P>
112      * Not all targets support this operation.
113      * Use {@link VirtualMachine#canUseSourceNameFilters()}
114      * to determine if the operation is supported.
115      * @since 1.6
116      * @param sourceNamePattern the pattern string to filter for.
117      * @throws java.lang.UnsupportedOperationException if
118      * the target virtual machine does not support this
119      * operation.
120      * @throws InvalidRequestStateException if this request is currently
121      * enabled or has been deleted.
122      * Filters may be added only to disabled requests.
123      */
124     void addSourceNameFilter(String sourceNamePattern);
125 }