BISMeta Annotations

De BIS Wiki
Ir para navegação Ir para pesquisar

As BISMeta são Java Annotations oferecidas pelo BISFrameWork que permitem que os VOs tenham informações sobre sua própria definição (Meta Dados): da classe e dos atributos.

BISMetaField

Os metadados disponíveis para atributos recebem o seguinte padrão de nome: "BISMeta" + <Tipo do Atributo> + <Nome Específico> + "Field". Sendo:

  • Tipo do Atributo - É o tipo do java que define o atributo. Ex: String, Integer, BigDecimal, etc.
  • Nome Específico - Essa parte só existe para alguns tipos de campos específicos. Por exemplo, para campos do tipo String que são usados como CNPJ a annotation BISMetaStringCNPJField pode ser usada para indicar que o atributo é um CNPJ.

Os Meta Dados que podem ser definidos dependem do tipo do atributo. Por exemplo para atributos do tipo String é possível informar o maxlength e minlength, já para atributos numéricos é possível informar valores mínimos e máximos, e assim por diante.

Alguns metadados são comuns para todas os atributos, são eles:

  • caption - Nome compreensível para o campo. Nome em português para o campo usado em mensagens de validação, na geração dos campos para a UI, etc. Embora não esteja sendo internacionalizado no momento, se em algum momento no futuro isso for necessário basta trocar os valores pelas chaves do Bundle e passar a resolve-las com o locale correto no momento do uso.
  • required - Obrigatoriedade. Define se a definição deste atributo é obrigatório ou não.
  • unique - Valor único entre os objetos existentes. Caso definido, indica que nenhuma outra instância do mesmo objeto terá o mesmo valor.

Alguns dos BISMetaFields existentes são:

  • BISMetaStringField - Conjunto de MetaDados para String.
  • BISMetaIntegerField - Conjunto de MetaDados para Integer.
  • BISMetaBigDecimalField - Conjunto de MetaDados para BigDecimal.
  • BISMetaEnumField - Conjunto de MetaDados para Enumerations.
  • BISMetaBooleanField - Conjunto de MetaDados para Booleans.

As BISMetaFields "personalizadas" permitem informar um uso específico para aquele atributo. Uma vez que o uso "personalizado" foi definido qualquer parte do sistema que leia as BISMetaAnnotations saberá como tratar o campo a partir das informações específicas. Algumas BISMetaFields para campos "personalizados" são:

  • BISMetaStringCNPJField - Transforma um atributo String em um atributo usado exclusivamente para CNPJ, já definindo tamanho máximo e mínimo, patterns, etc.
  • BISMetaStringCEPField - Transforma um atributo String em um atributo usado exclusivamente para CEP.
  • BISMetaStringPhoneField - Transforma um atributo String em um atributo para número de telefone no padrão do BIS: DDI|DDD|Telefone.


Java 256.png Exemplos de Uso
  /**
   * Define o nome da categoria.
   */
  @BISMetaStringField(caption = "Nome da Categoria", maxlength = 100, minlength = 3, required = true)
  private String name = null;

  /**
   * Define se o tipo desta categoria. 
   */
  @BISMetaEnumField(caption = "Tipo da Categoria", required = true)
  private CATEGORYTYPE categorytype = null;

  /**
   * Define um markup mínimo para a categoria.
   */
  @BISMetaBigDecimalField(caption = "MarkUp Mínimo", minIntegerValue = 0)
  private BigDecimal minmarkup = null;


BISMetaRelationshipField

A BISMetaRelationshipField é uma annotation especial para atributos a fim de declarar o relacionamento entre objetos. O relacionamento suportado é apenas entre BISDefaultVO. Esta annotation atualmente não suporta o relacionamento com outros tipos de objetos. No entanto, suporta relacionamento dentro de Listas e Hashs.

O relacionamento pode ser definido de dois tipos:

  • COMPOSITION - O Relacionamento de composição indica que o objeto sendo associado é um "sub conjunto" de informações deste objeto. No sentido que o objeto do relacionamento não existe sem este objeto. Quando este objeto for excluído ele deve ser excluído também! Afinal, ele é parte do objeto principal.
  • ASSOCIATION - A associação indica apenas um relacionamento entre dois objetos "distintos". Cada objeto tem sua própria existência independente da existência do outro. A exclusão de um não implica na exclusão do outro. Nesse tipo de relacionamento o objeto associado já existe no banco de dados previamente, não é cadastrado nem excluído em cascata.
Java 256.png Exemplos de Associação
  /**
   * Empresa associada.
   */
  @BISMetaRelationshipField(caption = "Empresa", relationship = RelationshipTypes.ASSOCIATION, required = true)
  private CompanyVO companyvo = null;


Java 256.png Exemplos de Composição
  /**
   * Guarda as configurações de cada empresa da categoria de itens.<br>
   * A chave é o ID da empresa, e o valor é o objeto com as configurações (<code>ItemCategoryCompanyVO</code>).
   */
  @BISMetaRelationshipField(caption = "Definições por Empresa", relationship = RelationshipTypes.COMPOSITION, required = true, moclazz = ItemCategoryCompanyMO.class)
  private List<ItemCategoryCompanyVO> itemcategorycompanylist = null;


BIS Constraints

BISContraints são um grupo de annotations à nível de classe, para a definição de meta dados da entidade/VO, não apenas do atributo.

BISAttributeRelation

Esta Annotation permite definir a relação entre dois atributos do vo, podendo mesmo ser um atributo em cadeia (dentro de outro objeto). É possível definir uma operação de comparação entre os atributos. Por exemplo, dois atributos devem ser iguais, dois atributos devem ser diferentes, um atributo deve ser maior que o outro e assim por diante.

É possível ainda indicar o próprio código de erro para o caso da relação não ser respeitada.


Java 256.png Exemplos de Relação entre Atributos
@BISAttributeRelation(attribute = ItemVO_._markup, attribute2 = ItemVO_._markupMin, operation = COMPAREOPERATION.MORETHAN, exceptioncode = "BISModules_000317")

BISUniqueConstraint

Esta annotation permite indicar um conjunto de atributos do VO que devem ser únicas. Similar ao UniqueConstraint do Banco de Dados, através desta annotation é possível indicar um conjunto de atributos e indicar que o conjunto todo não deve se repetir em nenhuma outra instância do objeto.


Java 256.png Exemplos de Unicidade em Conjunto de Atributos
@BISUniqueConstraint(fields = { ItemVO._name, ItemVO_._parentitemcategoryvo + "." + ItemCategoryVO_._id })

BISUsedBy & BISDependency

Estas duas annotations funcionam em conjunto, embora representem o oposto.

A BISUsedBy tem a finalidade de indicar que esta entidade é usada por outra, isto é, alguma instância desta entidade pode estar atualmente em uso por outra entidade. Quando uma instância está atualmente em uso ela não poderá ser excluída. A referência do BISUsedBy pode não ser sempre possível uma vez que o objeto pode ser utilizado por uma entidade de outro módulo/Plugin "desconhecido". Nestes casos ela não deve ser feita. Quando feita, é necessário passar dois parâmetros:

  • voclazz Classe da entidade que depende desta classe.

Ao declarar a BISUserBy é obrigatório que a classe com a dependência tenha a annotation BISDependency. Essa annotation tem a finalidade de indicar "como" uma entidade depende da outra. A BISDependency tem dois atributos:

  • voclass - que indica a classe da qual ela depende.
  • attribute - atributo que cria a dependência com a outra classe.

Note que a Classe que tem a BISUsedBy referencia o VO da classe que depende desta. Por sua vez, a classe dependente deve ter a Annotation BISDependency referenciando a entidade da qual depende. Abaixo um exemplo das classes ItemCategoryVO e ItemTypeVO, sendo que ItemTypeVO depende da ItemCategoryVO:


Java 256.png Exemplo de BISUsedBy e BISDependency
@BISUsedBy(voclazz = ItemTypeVO.class)
public class ItemCategoryVO extends BISDefaultVO {
  ...
}

@BISDependency(voclazz = ItemCategoryVO.class, attribute = "itemcategorylist")
public class ItemTypeVO extends BISDefaultVO {
  ...
}


Também é possível usar as annotations para indicar um relacionamento de dependência dentro da mesma entidade, como entidades hierarquicas. Cuja instância depende de outra instância da mesma entidade. Neste caso definimos ambas as annotations na mesma classe.

Java 256.png Exemplo de BISUsedBy e BISDependency em dependência cíclica
@BISUsedBy(voclazz = ItemCategoryVO.class)
@BISDependency(voclazz = ItemCategoryVO.class, attribute = "parentitemcategoryvo")
public class ItemCategoryVO extends BISDefaultVO {
  ...
}


Note 64.png
BISDependency não obriga BISUsedBy
Embora toda vez que seja usada a annotation BISUsedBy em uma classe torne-se obrigatório o uso de BISDependency, o contrário não é necessário. Caso uma entidade declare dependência de outra (usar a BISDependency) não obriga que a outra classe utilize a BISUsedBy.

Isso porque a classe que depende de outra obviamente conhece a classe da qual depende. Por outro lado, a classe que é "usada por" outra, não necessariamente a conhece, pois pode estar em outro projeto, módulo, plugin, etc.