Especificações de destino de sondas

Uma especificação de destino indica as classes e os métodos aos quais a sonda deve ser aplicada.

A especificação de destino é opcional. Quando não é especificado destino algum, a sonda é aplicada a todas as classes que sejam processadas pelo motor de instrumentação.

A especificação de destino permite criar regras de filtro para incluir ou excluir da instrumentação métodos baseados em padrões que correspondam ao nome, pacote e classe do método, além da assinatura do método. Os padrões podem conter caracteres globais, em que "*" corresponde a zero ou mais caracteres.

Se os padrões de caracteres globais de um destino corresponderem ao nome, pacote, classe e assinatura de um método, a propriedade type irá determinar se o método é instrumentado (include) ou não (exclude). Se os padrões não corresponderem ao nome, pacote, classe e assinatura de um método, por predefinição, o método é instrumentado.

O destino inclui as seguintes propriedades:
Propriedade Descrição
type Necessário. A propriedade type determina se é ou não aplicada uma sonda a um método destino. Especifique include para aplicar a sonda a classes e métodos que correspondam a padrões de caracteres globais, exclude para os excluir.
package Opcional. Especifique um padrão de caracteres globais para corresponder à parte de pacote de nomes de classe. Por exemplo: java.util* corresponde a cada classe no pacote java.util e respectivos subpacotes. Se não for especificado, o valor predefinido será *.
className Opcional. Especifique um padrão de caracteres globais para corresponder aos nomes de classe. Se não for especificado, o valor predefinido será *.
method Opcional. Especifique um padrão de caracteres globais para corresponder aos nomes de método. Se não for especificado, o valor predefinido será *.
signature Opcional. Especifique um padrão de caracteres globais para corresponder à assinatura de um método. (A signature é a cadeia de caracteres que representa os argumentos e o tipo de retorno do método.) Utilize o formato interno Java para assinaturas de método. Por exemplo: (Ljava/lang/Object;)D é a assinatura de um método que leva um Objecto como parâmetro e devolve um duplo. Este padrão de caracteres globais pode ser utilizado para distinguir entre métodos sobrecarregados. Se não for especificado, o valor predefinido será *.

Notas:

  • Uma sonda pode ter várias especificações de destino contendo regras de destino sucessivas. Para aplicar uma sonda somente a certos métodos, especifique primeiro os métodos que pretende incluir, e depois adicione uma especificação de destino final package=* className=* method=* signature=* type=exclude.
  • Os nomes de pacotes e classes que especificar também são verificados junto dos nomes de pacotes e classes de interfaces que a classe possa implementar. Por exemplo, java.util.HashMap implementa a interface java.util.Map. Se uma sonda fizer do pacote java.util, do nome de classe Map e do nome de método size o seu destino, a sonda será aplicada a java.util.HashMap.size(), e ao método size de qualquer outra classe que implemente a interface Map.
  • A correspondência de padrões não tem em conta relações de herança. Se a classe Derived expandir a classe Base, e uma sonda fizer de Base.run() o seu destino, a sonda não será automaticamente aplicada a Derived.run().
  • Se o padrão de pacotes numa especificação de destino for um único carácter de ponto final ("."), representa o pacote Java global, sem nome. Assim se permite constituir explicitamente destinos no pacote global.
  • As sondas de callsite fazem corresponder padrões e regras de destino ao pacote, nome, à classe e assinatura de um método chamado. A correspondência realiza-se no método chamado colmo era conhecido no momento da compilação; ou seja, nos nomes de classe e método estaticamente conhecidos, e não nos métodos propriamente ditos que serão chamados devido a funções virtuais e de herança. Se a chamada for efectuada através de uma referência de interface, o nome da interface deverá corresponder.
Exemplo:

Para especificar um destino, seleccione Destino na área de janela em árvore da página Sondas e faça clique em Adicionar e depois em Editar na área de janela de edição.

Este exemplo aplica a sonda somente a métodos cujos nomes comecem por Get em classes cujos nomes terminem em Proxy no pacote com.example. Entradas de destino dos tipos include e exclude; a entrada de destino exclude utiliza caracteres globais asteriscos para excluir tudo; a entrada include especifica os métodos exactos para constituirem destinos. Todas as outras classes e métodos estão excluídos da instrumentação.