Specyfikacje celu sondy

Specyfikacja celu określa klasy i metody, względem których sonda ma zostać zastosowana.

Specyfikacja celu jest opcjonalna. Jeśli cel nie jest zdefiniowany, sonda zostanie zastosowana do wszystkich klas przetwarzanych przez mechanizm instrumentacji.

Specyfikacja celu pozwala utworzyć reguły filtrowania, które będą uwzględniały w instrumentacji lub wykluczały z niej metody na podstawie wzorców dopasowywanych do nazwy pakietu, nazwy klasy oraz nazwy i sygnatury metody. Wzorce mogą zawierać znaki zastępcze, przy czym gwiazdka (*) oznacza zero lub więcej znaków.

Jeśli wzorce celu ze znakami zastępczymi pasują do nazwy pakietu, nazwy klasy oraz nazwy i sygnatury metody, właściwość type określa, czy metoda ma być instrumentowana (include) czy nie (exclude). Jeśli wzorce nie pasują do nazwy pakietu, nazwy klasy oraz nazwy i sygnatury metody, metoda będzie domyślnie instrumentowana.

Cel ma następujące właściwości:
Właściwość Opis
type Atrybut wymagany. Właściwość type określa, czy sonda ma być stosowana względem metody docelowej. Aby zastosować sondę względem klas i metod pasujących do wzorców ze znakami zastępczymi, należy określić wartość include, natomiast aby je wykluczyć, należy określić wartość exclude.
package Opcjonalna. Umożliwia określenie wzorca ze znakami zastępczymi pasującego do tej części nazwy klasy, która dotyczy pakietu. Na przykład wzorzec java.util* pasuje do wszystkich klas w pakiecie java.util i jego podpakietach. Jeśli ta właściwość nie zostanie określona, wartością domyślną jest *.
className Opcjonalna. Umożliwia określenie wzorca ze znakami zastępczymi pasującego do nazw klas. Jeśli ta właściwość nie zostanie określona, wartością domyślną jest *.
method Opcjonalna. Umożliwia określenie wzorca ze znakami zastępczymi pasującego do nazw metod. Jeśli ta właściwość nie zostanie określona, wartością domyślną jest *.
signature Opcjonalna. Umożliwia określenie wzorca ze znakami zastępczymi do dopasowania do sygnatury metody. Sygnatura to łańcuch reprezentujący argumenty i typ wartości zwracanej metody. Do definiowania sygnatur metod należy korzystać z wewnętrznego formatu języka Java. Na przykład wzorzec (Ljava/lang/Object;)D odpowiada sygnaturze metody pobierającej jako parametr wartość typu Object i zwracającej wartość typu double. Tego wzorca ze znakami zastępczymi można użyć w celu rozpoznania przeciążonych metod. Jeśli ta właściwość nie zostanie określona, wartością domyślną jest *.

Uwagi:

  • W sondzie może znajdować się wiele specyfikacji celu zawierających kolejne reguły określające cel. Aby sonda była stosowana tylko względem określonych metod, najpierw należy określić metody docelowe, a następnie dodać ostateczną specyfikację celu package=* className=* method=* signature=* type=exclude.
  • Definiowane w ten sposób nazwy pakietów i klas są także sprawdzane względem nazw pakietów i klas dowolnych interfejsów implementowanych przez klasę. Na przykład klasa java.util.HashMap implementuje interfejs java.util.Map. Jeśli jako cel sondy określono pakiet java.util, klasę Map i metodę size, sonda zostanie zastosowana względem metody java.util.HashMap.size() i metody size wszystkich pozostałych klas implementujących interfejs Map.
  • W dopasowywaniu do wzorca nie są uwzględniane związki dziedziczenia. Jeśli klasa Derived rozszerza klasę Base, a celem sondy jest metoda Base.run(), sonda nie zostanie automatycznie zastosowana względem metody Derived.run().
  • Jeśli wzorzec pakietu w specyfikacji celu jest pojedynczym znakiem kropki (.), reprezentuje on globalny, nienazwany pakiet Java. Pozwala to na jawne wskazywanie klas w pakiecie globalnym.
  • Sondy miejsca wywołania dopasowują pakiet, klasę, nazwę i sygnaturę wywoływanej metody do wzorców i reguł określających cel. Dopasowywanie jest wykonywane względem wywoływanej metody w postaci takiej, jak podczas kompilowania. Oznacza to, że są brane pod uwagę znane, statyczne nazwy klas i metod, a nie nazwy rzeczywistych metod wywoływanych w wyniku dziedziczenia i zastosowania funkcji wirtualnych. Jeśli wywołanie odbywa się przez odwołanie do interfejsu, musi pasować nazwa interfejsu.
Przykład:

Aby określić obiekt celu, należy wybrać pozycję Cel na panelu drzewa na stronie Sondy i kliknąć przycisk Dodaj, a następnie przycisk Edytuj na panelu edycji.

W tym przykładzie sondę zastosowano tylko do metod, których nazwy zaczynają się słowem Get w klasach, których nazwy kończą się słowem Proxy, które z kolei znajdują się w pakiecie com.example. Wpisy celów mogą być typu włączającego lub wykluczającego. Wykluczający wpis celu pozwala użyć znaku zastępczego gwiazdki w celu wykluczenia wszystkich obiektów. Włączający wpis celu określa dokładnie metody, który mają zostać uwzględnione. Wszystkie pozostałe klasy i metody są wykluczone z instrumentacji.