Harmonize toBuilder() implementations

[paullatzelsperger]

Feature Request

there are currently several slightly different implementations of the toBuilder() method around. We should harmonize that.

Which Areas Would Be Affected?

all classes that have a toBuilder method

Why Is the Feature Desired?

harmonization

Who will sponsor this feature?

Please @-mention the committer that will sponsor your feature.

Solution Proposal

• the toBuilder() method is to operate on the original instance, e.g.

  public Builder toBuilder() {
        return new Builder(this);
  }

  thus, any modification is done on the original instance.

• [optional] in addition, we could have a copy() method, which creates a completely new instance. We must be careful with deep copy vs shallow copy. This could be a sourcre for nasty bugs. Personally, I would opt for creating a deep-copy to maintain immutability of the original instance.

• Decision Record: docs: decision record about toBuilder and copy #4800