[tor-bugs] #22141 [Metrics/metrics-lib]: Deprecate `DescriptorFile` and add relevant information to `Descriptor`

[Tor Bug Tracker & Wiki]

#22141: Deprecate `DescriptorFile` and add relevant information to `Descriptor`
---------------------------------+-----------------------------------
 Reporter:  karsten              |          Owner:  karsten
     Type:  enhancement          |         Status:  needs_review
 Priority:  Medium               |      Milestone:  metrics-lib 1.9.0
Component:  Metrics/metrics-lib  |        Version:
 Severity:  Normal               |     Resolution:
 Keywords:                       |  Actual Points:
Parent ID:                       |         Points:
 Reviewer:                       |        Sponsor:
---------------------------------+-----------------------------------

Comment (by iwakeh):

 Replying to [comment:22 karsten]:
 > Replying to [comment:20 iwakeh]:
 > > Oh, only the interface was added.
 > > What could getAnnotations, getUnrecognizedLines return when called on
 an UnparseableDescriptor?
 >
 > Right now they don't return anything, that is, they return an empty list
 or `null`.
 >
 > But in theory we could return whatever annotations or unrecognized lines
 we found until running into a `DescriptorParseException`.  I have an idea
 how to build this with ''relatively'' little code changes, but I'll hold
 off until I hear whether that's even a good idea.

 No client would really want to use the possibly mangled content of these
 two methods, would they?
 A client would -- if at all -- use the raw bytes.

 >
 > Another solution that I don't like as much is that we introduce a new
 interface `ParsedDescriptor` that extends `Descriptor` and that other
 (parsed) descriptors extend.  That new interface could then contain these
 two methods, so they're not available in `UnparseableDescriptor`.  The
 part that I don't like there is that we'd have to deprecate the current
 methods in `Descriptor`, and applications depending on them would have to
 downcast their `Descriptor` instances to `ParsedDescriptor` instances just
 to get the annotations (or unrecognized lines).  Slightly eww.
 >
 > What do you think?

 I'd rather state in the javadoc that there won't be any useful content to
 expect.
 The methods could be simply returning the default or even be implemented
 to throw an exception "Not available".  That'll be sufficient.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/22141#comment:23>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online