close

Filter

loading table of contents...

Blueprint Developer Manual / Version 2101

Table Of Contents

4.4.7.4 Stubbing: Best Practices

You can use stub files to add annotations to classes and methods which are not part of your source code, that is especially third-party API and of course CoreMedia API.

Below you will find some practices which have proven to ease managing such stub files.

Naming Convention

While you may put all your stubs into one file, it is recommended to split it into smaller chunks to ease maintenance. For example, create a stub file for each third-party library.

A possible naming pattern is to use the Maven group and artifact ID within the filename. So for the artifact mongodb-driver-legacy within group org.mongodb a stub filename could be: org.mongodb.mongodb-driver-legacy.astub.

Stub Structure

Start with imports and especially start with importing the personal data annotations:

import com.coremedia.common.personaldata.*;

Then add packages and their classes, each in alphabetical order. Add methods in alphabetical or logical order to group getters and setters for example.

Stubbing Rules
  • In general, do not annotate parameters of methods that are intended for override. This may cause errors for existing code.

    class Collection<E> {
      boolean contains(@PersonalData Object o); // BAD!
    }
    

    While this sounds useful, it actually breaks existing code. Custom Collection implementations would cause errors as long as their parameter is not annotated as well. Because of that, it is better to use @SuppressWarnings("PersonalData") at usages of Collection#contains.

  • The stub parser of the ignores method bodies and modifiers and it is recommended to omit them for readability. However, adding static and final modifiers to methods and classes will make it easier to think about possible overrides (see previous rule). Parameters of static or final methods or final classes can easily be annotated because there cannot be any overrides.

  • There is no need to annotate all methods of a class or interface. However, it often makes sense to annotate similar methods equally. Overloaded convenience methods which just differ in the number of parameters should be annotated together to avoid confusion.

  • Sometimes it makes sense to annotate classes itself when instances of this class contain personal data and are passed to third-party methods.

    package java.security;
    
    @PersonalData interface Principal {
      @PersonalData String getName();
    }
    

    Reasoning: A Principal may be passed to some third-party method, which then possibly calls getName() internally. Because third-party internals are not subject to checking, you should already check the transfer of the Principal object to third-party libraries and either avoid it or allow it with @SuppressWarnings("PersonalData").

    Note that this rule just applies to stubbing: It does not make sense to use @PersonalData at interface source files when all code that uses that interface can be checked for personal data use. It is easier to just annotate method return values then. However, if a custom class or interface extends a third-party class/interface that is already annotated with @PersonalData, then the extending class/interface needs to be annotated in the same way:

    @PersonalData class MyPrincipal implements Principal {
      @Override
      public @PersonalData String getName() {
        return name;
      }
      // ...
    }
    

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.