Blueprint Developer Manual / Version 2304
Table Of ContentsYou 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 ofCollection#contains
.The stub parser of the ignores method bodies and modifiers and it is recommended to omit them for readability. However, adding
static
andfinal
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 callsgetName()
internally. Because third-party internals are not subject to checking, you should already check the transfer of thePrincipal
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; } // ... }