I'm pretty sure introducing an interface is a breaking change at the binary level. While it is source compatible, it will require recompile for anyone calling the method.
I personally am not a fan of adding "Interface" to the name of interfaces (or putting an "I" at the front). I like PDContentInstructionStream. If you choose a name like PDContentInstructionStream, you will probably also want to change the name of the abstract class to PDAbstractContentInstructionStream (or AbstractPDContentInstructionStream). The change is already breaking, so changing the name of that class is probably ok. Have you looked carefully at the design from a "single responsibility" perspective? I don't know how many methods you pulled up to the interface, but if it is a lot of methods, that might indicate a solid design review would be a good idea. I'm happy to take a look - but it will be a week before I can get to it. Finally, if backwards compatibility is a high priority, then changing the class to not be final would be the best approach. I prefer the interface approach, but sometimes backwards compatibility is more important than elegant design... K On Mon, Mar 3, 2025, 4:09 AM Tilman Hausherr <thaush...@t-online.de> wrote: > On 28.02.2025 18:07, Mark de Does wrote: > > Tilman, Others, > > To avoid reflections about the original intentions, let's go for the > interface approach. (Or can *John* be consulted?) I already typed the > code so that does not feel as a waste for me. > > That resolves some of the issues in my original mail. Lets recuperate: > > - Do you think introducing an interface is overkill? Simply making > PDAbstractContentStream public would achieve the same thing for me. :: We > go for the interface approach > - I chose the name PDContentStream for the interface. Later on, I > discovered it is an unfortunate name. :: I browsed ISO 32000-2:2020. In > 7.8.2 (*Content streams*) It defines a content stream as a sequence of > instructions. Would PDInstuctionStream be a good name for the interface? > - I moved the JavaDoc comments from the abstract class to the > interface. You agree? Or shall I also leave them in place? :: Agreed to > move? > - On which branch must I base my PR? (I see that the trunk already has > a 4.0 version number) :: I am jumping to get this now! What can I do to get > this in the next 3.something release? (As far as I can judge.. This widens > the API interface and does not change anything functionally) > > Hi, > > I added a link to the ticket. You're welcome to apply for an account - > just include something that we know it's you. I agree with the javadoc > move. PRs should be against the trunk so OK. > > I'm not sure if it is a breaking change. I think it isn't, but ChatGPT > says it is, but reading its reasoning makes me think it isn't. > > I don't like the name, why not PDContentStreamInterface? Yes it is > confusing that we have a PDContentStream interface. I'd wait a bit for > other opinions. > > John is still member of the project but hasn't been active since then. > > Tilman > > > > > - > > Greetings.. Mark. (Sorry for being pushy) > > -- > Mark de Does, Magdalenastraat 6, 3512 NH Utrecht, the Netherlands > <https://www.google.com/maps/search/Magdalenastraat+6,+3512+NH+Utrecht,+the+Netherlands?entry=gmail&source=g>,http://maps.google.nl/?q=52.08692,5.1271, > e: m...@mdedoes.xs4all.nl t: 030 2314150 > > On 28-02-2025 14:40, Tilman Hausherr wrote: > > Making PDAbstractContentStream public seems to be the easier solution, > but: > It was created package-private. I don't know if (1) John had a specific > reason for it or (2) this was just "best practice" to make stuff restricted > until somebody requests it to be accessible. However he wrote "unless we > want users to subclass PDAbstractContentStream" so he wanted to prevent > that, so it would be (1). That makes me undecided. > > See here: https://issues.apache.org/jira/browse/PDFBOX-4068 > > Amusingly not only this is still open but it was me who created it 🤦♂️ > > Tilman > > On 28.02.2025 14:22, Mark de Does wrote: > > In one of my projects, I convert (a subset of) SVG to PDF, using PdfBox. > > In SVG, the contents of the main <svg> element, the <marker>, <symbol> and > <pattern> definitions have the same syntax and structure. With PdfBox 2, I > use a PDPageContentStream to record the content of all three. With PdfBox > 3, that no longer works because I must use a PDPatternContentStream to > record a pattern. Because the different kinds of content stream do not > share a visible (public) ancestor, I cannot use the same code to record SVG > content to a content stream. > > This morning, I captured the public methods of PDAbstractContentStream in > an interface and declared PDAbstractContentStream to implement that > interface. I adapted my code to use the interface and everything works > fine. (As expected). > > Before I make a PR, I need some guidance. > > * Do you think introducing an interface is overkill? Simply making > PDAbstractContentStream public would achieve the same thing for me. > (The class, not the constructor) > * I chose the name PDContentStream for the interface. Later on, I > discovered that is an infortunate name: A different interface with > that name already exists. What would be a better name? > * I moved the JavaDoc comments from the abstract class to the > interface. You agree? Or shall I also leave them in place? > * On which branch must I base my PR? (I see that the trunk already has > a 4.0 version number) > > Thanks and Greetings.. Mark > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: users-unsubscr...@pdfbox.apache.org > For additional commands, e-mail: users-h...@pdfbox.apache.org > > >
