r/java • • Feb 08 '22

Java's Options for Options

https://mccue.dev/pages/2-8-22-options-for-options
192 Upvotes

80 comments sorted by

16

u/Az4hiel Feb 08 '22

Even though lack of taking any definitive stance by the author on what they consider best seems a little disappointing (although definitely right, everything is a trade off and there is no way around it) - the whole thing was a wonderful read. It was quite heartwarming to see that other people also think in such terms about code... and share the frustration ;)

10

u/bowbahdoe Feb 08 '22

its 13

10

u/Az4hiel Feb 08 '22

Honestly my default approach definitely is enumerating possibilities via methods (as usually most feature combinations are not needed and it seems easier to control possible states this way) - but you have definitely showed that this approach has its "roof" - too many combinations are just killing readability.

Given slightly sarcastic tone I was expecting that you would lean towards not implementing unnecessary features - in the spirit of best repository being empty repository :D

1

u/sintrastes Feb 09 '22

What about assuming hypothetical 4?

I like 23 and 21.

1

u/bowbahdoe Feb 09 '22

Oh, I was joking. I thought 13 was the worst at 8 options

29

u/jokubolakis Feb 08 '22

What did I just read and where can I get more

24

u/bowbahdoe Feb 08 '22

Give me like - I dunno - a week and a half

1

u/Lvl999Noob Feb 10 '22

I liked this post. I tried looking if you had more of your posts. Is there no list of posts or something? I managed to find your github, assuming this was a github pages site, but that also doesn't seem the case.

1

u/bowbahdoe Feb 10 '22

There is an index page - it's all pretty low quality though. I'll find a way to link back for next one

51

u/Scybur Feb 08 '22

I was hoping for a nice solution at the end but instead I was left with disappointment.

10/10 good read.

6

u/davewritescode Feb 09 '22

A nice solution from Kotlin is named parameters with default values.

1

u/renatoathaydes Feb 12 '22

Haha, yep, solved the problem completely with one simple stroke. Dart also does that and because of that, allows really complex objects, like Flutter Widgets, to be created easily... it's definitely the best way to go.

19

u/[deleted] Feb 08 '22

[removed] — view removed comment

5

u/TenYearsOfLurking Feb 09 '22

This differs from a config object how exactly?

7

u/[deleted] Feb 09 '22

[removed] — view removed comment

8

u/TenYearsOfLurking Feb 09 '22

You are right, but my point was: you are offering syntactic sugar (merging config object and invocation) not "solve" a problem. I'd argue yt make it worse because explicit arguments before are now implicit since the depend if some setter was called before. It's a design tradeoff. As always

1

u/renatoathaydes Feb 12 '22

Using setters is not necessary, just make the object immutable... it still contains all the settings, but you can't change them. If different code needs different settings, they just create different objects.

1

u/TenYearsOfLurking Feb 12 '22

Does not change the fact that explicit parameters of the call are becoming implicit now.

2

u/renatoathaydes Feb 12 '22

That's usually a good thing. Passing the whole environment on each function call might work well in Haskell, but in Java we have better ways.

-8

u/[deleted] Feb 09 '22

[removed] — view removed comment

5

u/TenYearsOfLurking Feb 09 '22

It has advantages and disadvantages. The next call would depend on the previous calls settings. You may want that behavior or not. It really depends, so i take back that it's worse.

4

u/[deleted] Feb 09 '22

That's exactly what the two major JSON libraries (Jackson and Gson) for Java do

-1

u/Pyeroh Feb 09 '22

Java is not .NET, maybe that's why it doesn't follow the same patterns... Ready to get downvoted !

2

u/[deleted] Feb 09 '22

[removed] — view removed comment

2

u/Pyeroh Feb 09 '22

Indeed, but it involves differences between communities, guidelines intended by the language architects, usages, and so on. Not something one could change anyway.

So a statement like "Java would be easier if they'd do like language X" is an elaborate "I prefer X over Java", which is not very constructive. Maybe that's just me, but when I browse r/java, I expect to find content about Java, high-end patterns and practices in Java, and not guidelines from another language which don't fit the Java culture.

15

u/schubart Feb 08 '22

Option 10: I’d take a Set<Indent> rather than an EnumSet<Indent>. No need to force the caller to use the verbose noneOf syntax.

7

u/DasBrain Feb 09 '22

Option 11: I add an overload with a variadic Option... parameter.

21

u/BlueGoliath Feb 08 '22

This is hilarious. 10/10

10

u/agentoutlier Feb 08 '22

Here is how I would do it.

I make JsonWriter an interface and one simple implementation.

Than I delegate to Spring Source to make every option as a class that implements the interface.

CopyrightNoIndentArrayJsonWriter

It’s a huge combinatorics problem but rest assured the spring guys are used to solving this problem with lots of classes.

Oh there is probably some spring boot jars that work 70% of the time to get the 20% of the 80% but not the 80%.

1

u/Michigan__J__Frog Feb 09 '22

How do you do that? Or what is it called, so I can look into it?

1

u/torwinMarkov Feb 08 '22

Cute, but you're not separating your concerns. This reads very much like how my junior devs at work think about problems. Here are your requirements:

  1. Output JSON text (in any format)

  2. Format / style JSON (separate concern)

  3. Amend JSON payload (with copyright)

  4. Output as binary

Taken as separate tasks with silo'd requirements, your hypotheticals become much easier to think about, solve, and test. For more, I recommend reading "Clean Code" by Robert C. Martin.

44

u/bowbahdoe Feb 08 '22

aww, thanks. ur cute too

14

u/Az4hiel Feb 08 '22

You sure you understood the premise of the article, mate?

22

u/[deleted] Feb 08 '22 edited Feb 08 '22

Are you sure you understood the premise of the objection to the article?

Instead of providing all of those options as a tangled mess if statements, enums, options or whatever, just use composition. You can break down the problem into individual responsibilities and then compose the responsibilities.

For example:

Hypothetical 1: Compact vs. Pretty

public class CompactJsonWriter implements JsonWriter {
}

public class IndentingJsonWriter implements JsonWriter {
}

Hypothetical 2: Hybrid of compact and pretty

Instead of having a single IndentingJsonWriter, do this instead:

public class DefaultIndentingJsonWriter extends IndentingJsonWriter {
    // Or make this a static factory method of IndentingJsonWriter if you really hate inheritance
    public DefaultIndentingJsonWriter() {
        super(
            new DefaultObjectIndentingStrategy(),
            new DefaultArrayIndentingStrategy()
            // I don't think JSON has any other things that can be indented
        );
    }
}

IndentingJsonWriter myFunkyJsonWriter = new IndentingJsonWriter(
    new DefaultObjectIndentingStrategy(),
    new CompactArrayIndentingStrategy()
    // CompactJsonWriter could actually be composed of all compact intenting strategies
);

Hypothetical 3: Inject copyright

By wrapping the writer in a proxy, it doesn't matter what combination of options you use. The proxy doesn't have time for any of that.

public CopyrightInjectingJsonWriter implements JsonWriter {
    public CopyrightInjectingJsonWriter(JsonWriter proxied) {
        this.proxied = proxied;
    }

    public void writeJson(Appendable out, Json json) { 
        // Is it legal? I will make it legal.
        Json json = addCopyright(json);
        proxied.writeJson(out, json);
    }
}

Hypothetical 4: Binary

You just wrap the Appendable in a BinaryAppendable. I have no idea what an Appendable is, but I'm going to assume it's something like an OutputStream or a Writer, but knows that it is writing JSON (and potentially wraps an OutputStream or Writer). In which case the BinaryAppendable will intercept writes to the Appendable and convert them to a binary encoding.

When you do stuff like this, you have to be careful, since the mapping isn't one-to-one, so composition order matters. For example, if you wrap an InputStream in a BufferedInputStream, make sure no one can ever interact with the wrapped InputStream.

public BinaryJsonWriter implements JsonWriter {
    public enum Endianness {
    }

    public BinaryJsonWriter(JsonWriter proxied, Endianness endinaness) {
        this.proxied = proxied;
        this.endianness = endianness;
    }

    public void writeJson(Appendable out, Json json) {
        proxied.writeJson(new BinaryAppendable(endianness, out), json);
    }
}

8

u/bowbahdoe Feb 08 '22

Can you leave those as a comment on the article?

4

u/[deleted] Feb 08 '22

I'm at work and my company decided to block your blog, but my overlords can't keep me from reading your article on my phone. I don't feel like trying to copy over a bunch of code on a 6-inch screen. But if you liked the comment, feel free to copy it over.

1

u/bowbahdoe Feb 09 '22

And to be clear on the last one - at least with MessagePack it doesn't take JSON text and just turn it into bytes, it's an actual byte format that matches the JSON data model. BinaryAppendable wouldn't be able to do its job.

Still, toy example.

1

u/[deleted] Feb 09 '22

Like I said, I don't know what an Appendable is.

But if it works anything like Jackson, the Json object is written through a generator (JsonGenerator) which actually writes out JSON tokens. Using this approach, Jackson can just as easily write straight text JSON (UTF8JsonGenerator) or various binary formats related to JSON (CBOR - CBORGenerator or Smile - SmileGenerator). Jackson gets even crazier with a YamlGenerator (which lets you write JSON as YAML file) and ToXmlGenerator (ditto for XML).

The sky is the limit with composition.

2

u/bowbahdoe Feb 09 '22

Ah, Appendable is a built in Java interface that basically let's you write one byte at a time. It's more or less an OutputStream.

I also now see you mentioned that caveat. Ignore me

1

u/[deleted] Feb 09 '22 edited Feb 09 '22

I see that you're just playing around with ways of supporting a bunch of different options, using JSON generation as a toy example.

If you want to see how this is done in real life, you should probably look at what a real, production JSON library does, which has to support all the crazy things that people want to do. All your hypotheticals can be easily be implemented in Jackson, simply by plugging in an appropriate interface implementation without the giant messes in your blog post.

Hypothetical #1 is already there, without indentation you have MinimalPrettyPrinter and with indentation DefaultPrettyPrinter.

For Hypothetical #2, if you want to implement your own pretty printing rules, write your own PrettyPrinter implementation.

For Hypothetical #3, wrap an existing JsonGenerator with a custom JsonGenerator which inserts the copyright.

For Hypothetical #4, use a binary generator like CBORGenerator or SmileGenerator. If you want to insert copyright, wrap the binary generator with the copyright-inserting generator.

Spring is another example of a library which supports an insane number of options by composing interfaces. I have bent and twisted RestTemplate to do insane things, simply by implementing the right interfaces, while actual client code making REST API calls using the RestTemplate is none the wiser.

For example, I integrated RestTemplate with a particularly terrible SSO library which added the appropriate auth cookies to the request, but I had to buffer the whole thing first. I had to construct a Rube Goldberg contraption within a custom implementation of ClientHttpRequestFactory, but it worked.

4

u/Thysce Feb 09 '22

Nice response. Little hint: as others mentioned here before, your Proxy would be more well-named as a Decorator.

3

u/TenYearsOfLurking Feb 09 '22

Are you suggesting that it is a good API if the consumer must exactly know which subtype of JsonWriter to instantiate? Which explode in complexity if more options are added. Which require to instantiate obscure "Strategy" objects instead of an enumeration which clearly and exhaustively(!) shows the available "modes".

Instead of browsing the api java doc for the X classes needed, it might be preferable to offer a single entry point, where the IDE shows all parameters that can or must be filled via techniques explained in the article.

It always depends. To present your (enterprise-y) solution as strictly better is... lets say "debatable"

4

u/[deleted] Feb 09 '22 edited Feb 09 '22

Are you suggesting that it is a good API if the consumer must exactly know which subtype of JsonWriter to instantiate?

I think so. But then again, I've been using OOP APIs for years. If you use a decent enough IDE, it's actually very easy to enumerate all the available types of interfaces/base classes to instantiate. For example, if I hit Ctrl+T on the Jackson JsonGenerator base class, IntelliJ will show me every available type of JsonGenerator available on the classpath. In fact, that's how I learned it is possible to configure Jackson to generate YAML (YAMLGenerator).

Which explode in complexity if more options are added.

The complexity does not explode. In fact, there is a specific metric that can be used to measure complexity - cyclomatic complexity. Composition is branchless, while adding a bunch of feature flags and corresponding if statements significantly increases complexity, in combinatorial fashion. You can even put a number on it!

instead of an enumeration which clearly and exhaustively(!) shows the available "modes"

There are two things wrong with this statement.

First, a modern IDE will clearly and exhaustively show you the available "modes" through available interface implementations.

Second, you are limited by the modes baked into the API if you use feature flags. Jackson, because it uses OOP techniques for extension, is unlimited in the modes that are available.

To present your (enterprise-y) solution as strictly better is... lets say "debatable"

In my experience, what you call the "enterprise-y" approach leads to much more flexible libraries. For example, Spring's RestTemplate is also built around the same principle of strategy interfaces. I have been able to adapt RestTemplate to situations never imagined by its authors. This has allowed me to use Spring in situations where I might not have been able to use a more rigid library.

1

u/WikiSummarizerBot Feb 09 '22

Cyclomatic complexity

Cyclomatic complexity is a software metric used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program's source code. It was developed by Thomas J. McCabe, Sr. in 1976. Cyclomatic complexity is computed using the control-flow graph of the program: the nodes of the graph correspond to indivisible groups of commands of a program, and a directed edge connects two nodes if the second command might be executed immediately after the first command.

[ F.A.Q | Opt Out | Opt Out Of Subreddit | GitHub ] Downvote to remove | v1.5

2

u/Az4hiel Feb 09 '22 edited Feb 09 '22

These are completely valid propositions, yet, completely missing intention of my question. Things can be done differently, true, perhaps better even, sure - still - proposing improvements is imho missing the main point (as it seems orthogonal to the article).

Have you heard of confirmation bias? It is kinda good example - instead of trying to understand what I asked (or really just asking for clarification) you developed argumentation to confirm your stance... such a thought pattern usually leaves space for missing something.

To reiterate as I have no intention of "winning" any argument here or something: you seem smart, these propositions have value as extended discussion, tone in the initial comment seemed condescending and was at least critical of article not showing the better way to do things - I don't think author was trying to do that. I think author was mostly playing with different ideas and showing their interplay and how everything can go to shit. I think it is a very real process and making people aware of it is valuable on its own (also it cleverly avoids the risk of suggesting wrong solution for specific context - which I respect).

Sorry for not posting under the article OP.

Edit: not the same person in the first and second comment - my mistake

0

u/[deleted] Feb 09 '22

Uh, you did the same thing to the guy you replied to.

2

u/Az4hiel Feb 09 '22

If you mean first comment:

How? I think there is a difference here - note that I asked a question, and didn't just start explaining what I believe is the correct interpretation. What motivated my to ask was recommending reading "Clean Code" and (frankly, quite rude sounding) comparison with "my junior devs" - which striked my as unjustified given (perceived by me) intellectual quality of OP article.

If you mean yourself:

I think I understood and recognized your proposition as valuable - which also makes the difference imo. Please correct me if you see it differently.

0

u/[deleted] Feb 10 '22

[deleted]

2

u/[deleted] Feb 10 '22

If you leave your API open to extension, it might be possible to compose responsibilities in the wrong order. That is the price you pay for your API to be adaptable to any circumstance.

Otherwise, you have to strictly limit features to control permutations to ensure that it is impossible to use incorrectly.

At the end of the day, a more flexible API will have better survival characteristics (more people will use it) than a perfect API that is both convenient and impossible to use incorrectly.

1

u/TenYearsOfLurking Feb 09 '22

What a stupid, condescending answer. You cannot magically model away complexity with OO patterns. There is always a tradeoff and in the end you have to tackle all combinations somehow.

In this case the design goal is clearly a sensible, easy API for consumers, not maximum testability.

5

u/[deleted] Feb 09 '22

What is ironic about your response is that all of the complexity that the OP listed is indeed "magically modelled away with OO patterns" by Jackson, a real JSON library with an "easy API" for consumers.

The benefit of Jackson's OO model is that the complexity in OP's toy example is hard coded in the API, but Jackson has no knowledge of OP's requirements but can be extended to support them, nonetheless. Thanks to OO patterns.

4

u/TenYearsOfLurking Feb 09 '22

Jackson has, exactly like the example, at least a single entry point. that is ObjectMapper.readX or writeX, that are overloaded as seen in the article.

see my comment here: https://www.reddit.com/r/java/comments/snrfek/comment/hw7jloz/?utm_source=share&utm_medium=web2x&context=3

There are no free lunches. everything comes at a tradeoff and the cost of a highly compositional API is, well, that you must dig into all composition options yourself instead of using a clear well defined entry point.

And to say: "an pure OO solution is superior, you code like a junior, go read a book" - is condescending and negates the benefits of the presented solutions.

Side note: "clean code" got a lot of negative attention recently, you might want to look that up before you recommend it to anyone

2

u/[deleted] Feb 09 '22 edited Feb 09 '22

Jackson has, exactly like the example, at least a single entry point. that is ObjectMapper.readX or writeX, that are overloaded as seen in the article.

That's the Law of Demeter, and is not the same as the method of overloading in the article. That is, these are convenience methods for the most common cases. If the convenience methods don't do what you want, you can directly instantiate ObjectWriter or ObjectReader.

you must dig into all composition options yourself

That's easy with modern tools. Ctrl+T will show you all of the composition options at a glance in IntelliJ.

an pure OO solution is superior, you code like a junior, go read a book

A pure OOP solution is superior to OP's approach, and the way OP did it is how many juniors do write code, because they haven't learned the more advanced techniques available in Java.

"clean code" got a lot of negative attention recently

So? It's a book. It's got good stuff and bad stuff. I got something out of it, so I recommend the book.

2

u/TenYearsOfLurking Feb 09 '22

Okay then please enlighten me why the java standard library has implementations like java nios Files.write(). Are only juniors working on the standard lib? Is it not always superior to have a CharSetFileWriter for the overload that takes a charset? Is the StandardOpenOption better replaced by an OpenStrategy... etc, etc. I could point you to a lot of other examples.

Or is it maybe that there is a tradeoff and extensibility does not always beat simplicity?

1

u/[deleted] Feb 09 '22 edited Feb 09 '22

Are only juniors working on the standard lib?

That is not what I said. I was talking about the approach the OP took. The OP's approach was a giant mess, which I assume was the gimmick behind his post.

Files.write() is an interesting case, which actually does not prove what you think it proves.

Do you know what my IDE tells me? Files.write() is a static utility method that operates on an abstract Path, which leads to some interesting observations.

Inside Files.write(), you have this construction:

OutputStream out = Files.newOutputStream(path, options)

is shorthand for:

path.getFileSystem().provider().newOutputStream(path, options)

And Path itself is an interface which represents an abstract path that you get from a FileSystem (this time an abstract class). The FileSystem class is it's own rabbit hole, in the classic Java sense. You can have any number of FileSystem types available to you through the SPI system which allows you to extend Java in arbitrary ways. Which leads to cool things like the static FileSystems.getFileSystem(URI) method, in which Java will try to find a FileSystem that can handle the URI scheme (file://, http://, ftp://).

So, Files.write() could write a file to disk or it could upload a file to a web server. Who knows?

You're only looking at static utility methods (like the Collections utility class) without seeing the massive extensibility that those static methods are generically operating on (such as the Collections API).

Java has always been a mix of static utility classes operating on massively extensible universes of things.

Indeed, Files.write() basically proves my point.

3

u/TenYearsOfLurking Feb 09 '22

I will stop here with a final remark. I am not saying you are wrong, you are just failing to see that the article is clearly about API design. not the implementation which might be composable and extensible under the hood, that's not the point.

I tried to make a point that the goal of, either jackson, or the standardlib files.write was simplicity and ease of use, as well as discoverability without searching the type hierarchy.

Both prove THAT point.

1

u/[deleted] Feb 09 '22 edited Feb 09 '22

you are just failing to see that the article is clearly about API design

It is, and you're missing the point.

OPs design ideas aren't composable or extendable. The capabilities of OP's API is locked to whatever the OP came up with. The mess the OP was making trying to extend his toy API proved how poorly it was designed.

The front ends to Java and Jackson are merely conveniences, utilities, but ultimately both Jackson and Java can be infinitely extended using OOP principles and are indeed designed around OOP principles. This is the difference between a junior (as the guy at the top said) and someone who understands OOP.

You clearly are not seeing that OP's API design approach is nothing like the API design approach behind either Java or Jackson, which are elegant OOP designs (as opposed to the mess that OP made). You are comparing apples and oranges.

1

u/sintrastes Feb 09 '22

What's the negative attention for "clean code"?

-2

u/TenYearsOfLurking Feb 09 '22

hey, have you tried this new thing "google"? it gives you page results on search queries, how cool is that? e.g. this one: https://qntm.org/clean

1

u/sintrastes Feb 09 '22

Wow! No. I totally haven't. That's pretty radical, man. Crazy times we live in.

0

u/[deleted] Feb 09 '22

[deleted]

1

u/TenYearsOfLurking Feb 09 '22

Guilty, but c'mon be fair: it's not the same to dismiss a high effort blog post like that as opposed to not even make the effort of typing 3 words into Google, but instead asking for the search results

5

u/yanitrix Feb 09 '22

Option 0: Ignore whitespaces

5

u/GreenToad1 Feb 09 '22

I really like the idiom that is popular in C# that would go like this:

writeJson(out, json, options -> {
    options.indentObjects();
    options.indentArrays();
});

1

u/HighRising2711 Feb 10 '22

Why is the method static? Can't you instantiate an object, call setters to configure the object then use the object?

Or if you prefer, use a builder to configure and instanciate then use the object

1

u/bowbahdoe Feb 10 '22

Yep. that solution is shown in the comments

5

u/Milyardo Feb 09 '22

One option missing is to use function composition and accept a higher order functions.

public static Function<String, String> indentObjects = ...
public static Function<String, String> indentArrays = ...
public static Function<String, String> indentEverything = indentObjects.compose(JsonWriter::indentArrays)
public 

public static void writeJson(Appendable out,
        Json json, Function<String, String> format) {
    ...
}

writeJson(out, json, Function::identity)
writeJson(out, json, JsonWriter::indentEverything)

6

u/talios Feb 09 '22

Face it - you want.... monads

4

u/b00n Feb 09 '22

You shouldn't accept Optionals as input parameters because you can't actually guarantee that the Optional itself isn't null. So given you still need a null check it's pretty pointless.

3

u/CptGia Feb 09 '22

If the user passes a null for an Optional, they deserve the NPE.

2

u/persicsb Feb 09 '22

Also true for Optional return values. One cannot be sure, that a returned Optional isn't null, because programmers are sloppy.

2

u/b00n Feb 09 '22

It is also technically true but I have more faith in a library author doing it correctly than a sloppy end user.

1

u/renatoathaydes Feb 12 '22

Those guys tend to be the same, you know?

2

u/FewTemperature8599 Feb 10 '22

I've never seen this happen once, across thousands of repos, millions of lines of code, and thousands of engineers

3

u/[deleted] Feb 08 '22

ok. from now on, I return to XML.

1

u/Just_Another_Scott Feb 09 '22

Shiiiiiit I've gone down that exact path in meetings before with our API lol. I just advocate returning the JSON and letting the consumer format it however they want which is the ultimate solution given at the end of the article. Pick one and let the consumer decide how to output it.

1

u/severoon Feb 18 '22

I don't understand, it seems like the point of this class is to write input as valid JSON. So it should do that, and only that, as compact as possible.

If there's new requirements to have the JSON formatted, what's that got to do with the JSON writer? Create a new class that formats JSON.

It's easy to create all sorts of problems in an API if it breaks SRP.

0

u/[deleted] Feb 08 '22

[deleted]

-1

u/TenYearsOfLurking Feb 09 '22

Please add the link to Brian's stack overflow answer. There must not be any mention of optional in this sub without it