
AWS Java documentation is fucked - AReallyGoodName
https://areallygoodrantblog.wordpress.com/2016/02/13/the-aws-java-documentation-is-fucked/
======
jcrites
The article is discussing documentation for the _AWS Flow Framework
specifically_. The Flow Framework is a Java framework built on top of the SWF
API, and it provides a completely different programming model than the SWF
API.

The C# example being discussed, as well as the Java example at the end, are
examples of using that SWF API directly. The SWF API is indeed simpler for
trivial examples. Flow is a power tool that handles complex workflows better
than any alternative I've seen, but the framework itself is complex and incurs
cost to set up and use. The documentation could do a better job of explaining
this, and of providing Java API examples.

The Flow framework provides something that's a mix of Java code and a domain-
specific language for building SWF applications that's expressed as Java code.
(For an analogy, consider EasyMock.) It's hard to explain Flow concisely, but
if I had to try I'd say, "You write code that looks like it's procedural and
runs on one machine, and Flow converts that into a distributed workflow
running across of fleet of machines, all of which may be stateless". Flow
threads the state into and out of SWF for you, making it possible to express
distributed workflows at a higher level of abstraction. Some examples are in
the AWS Flow Framework Recipes:
[https://aws.amazon.com/code/2535278400103493](https://aws.amazon.com/code/2535278400103493)

To achieve this, Flow uses fancy code weaving & AOP techniques. This makes it
more complicated to set up, develop, and test. Flow pays off however once your
workflow is more complex than a simple linear workflow. You could, for
example, process data with a distributed map/reduce pattern in a few lines of
code in Flow. (Source: built production systems on SWF with and without Flow)

~~~
AReallyGoodName
It's unfortunate that it's the first Java example provided for anything to do
with SWF. I got dumped into that from the "what is SWF" page. There's no
simple Java SWF example like there is for C#. The docs dump you straight into
the Flow Framework.

I'd argue based on Occams Razor that a more simplistic start is what most
people want. Unfortunately to get that you have to look at the documentation
of another language.

~~~
deanCommie
The counter argument is Flow IS what you want. Why poll for decision tasks and
try to schedule the work execution between different servers when SWF Flow can
do it for you?

All the things you found irritating are a one-time setup, and once you are
chugging along you can write incredibly quickly powerful distributed systems
without worrying about scaling or scheduling of any kind.

But I agree the documentation could do a better job of SELLING you on that
point up-front.

Truth is, I don't know of any other framework or service that allows you to
simply write java code like this:

A = getA(); B = getB(); C = getC(A, B); D = getD(C); E = getE(B);

Assuming all these getCalls are complex, time-consuming, and stateful, Flow
automatically sets it up so that at the start getA() and getB() start
executing in parallel (and on different servers!), getE() i immediately
started once B is realized, getC() is immediately executed once both A and B
are both realized, and so on.

For complex workflow with undetermined execution time where the whole thing
may take days to execute, the fact that you can just tweak a simple Java file
to update your business logic, and add some servers to your fleet whenever you
want to improve throughput is MAGICAL.

Not all problems in software are simple to abstract away. I think Flow does
the best it can do

------
hoodoof
This is the start of the path to not using Java.

And it's not so much about AWS quality of Java documentation.

It's just about "why the heck does everything Java have to be so damn
heavyweight and so damn hard".

Everything in the Java ecosystem is hard. I generally don't care so much about
what language something is built in but I do try really hard not to use major
applications written in Java. Life is too short to spend my days fighting
through thickets of XML tags to try to get something configured, or installing
something that seems to be constructed from hundreds or thousands of files.

Use a different language and some things aren't so hard any more.

I will say that the exception is the JetBrains IDE that I use most of the day
is built with Java and somehow they have managed to shield me from ever
needing to even know that.

Friends don't let friends use Java.

~~~
peeters
> Everything in the Java ecosystem is hard.

It really isn't. I request that you qualify your comments to the subset of the
"Java ecosystem" that you actually have experience with. Because "thickets of
XML tags" really has nothing to do with Java, though it might have to do with
certain massive frameworks built on top of Java.

~~~
geofft
I'm curious, what parts of the Java ecosystem (other than simple stuff, or old
stuff, or non-Java languages on the JVM) _don 't_ involve thickets of XML
tags? I have so little Java experience that it's fallen off my résumé, so I'm
sure I'm uninformed and would like to be more informed. But everything I've
seen of actual, production Java development today heavily uses XML somehow,
from Ant or Maven build files, to web.xml, to Spring dependency injection, to
Android, to even Java Web Start.

Is there any serious part of the Java (Java, not Scala or Clojure) ecosystem
that doesn't involve XML at every corner?

~~~
rnovak
Well, for starters, Spring basically has eliminated XML configuration with
Spring-Boot. Add a couple annotations and you're done (as in, fully done, no
web.xml's, no application-contexts). (Granted, I don't really like this, from
an engineering point of view, but whatever).

Also, I really wouldn't complain about Maven, as it is _hands down_ the best
dependency manager available from _any_ language, bar _maybe_ gem/rails (node
isn't even close, since you need a c++ compiler to actually get quite a few
packages). There are also enough plugins for every IDE out there to handle
Maven POM's.

But if that wasn't enough, there's now Gradle. You can literally have an
entire Spring/Java/Grade project that doesn't use _ANY_ XML, but purely
Annotations/DSLs.

Secondly, there's a major selection bias at play. In your own words
"everything _I 've_ seen of...", sorry but your point was lost right there.

Yes. I've seen (and written) plenty of _actual_ production Java code that
doesn't use any XML configuration at all.

There are a lot of issues with Java, but XML isn't _INHERENT_ to it.

~~~
orf
> as it is hands down the best dependency manager available from any language

Why? You don't back that statement up with anything. What makes it better than
`pip`?

> node isn't even close, since you need a c++ compiler to actually get quite a
> few packages

Well if the packages contain C/C++ modules and don't distribute binaries...
(which a lot do). In Python land packages with a C++ module normally have a
pure-python fallback anyway.

~~~
soofaloofa
Recently moving from Python to Java. `pip` doesn't even come _close_ to Maven.
Dependency management used to be something I needed to manage much more
closely in Python. With Maven, it just works.

~~~
orf
I'm just curious as to why. You specify a list of requirements and their
versions, and those get pulled down from somewhere and installed locally. What
makes Mavens process far superior to pip (or npm, or any other program)?

~~~
rnovak
Because with JVM languages, and their "horrid" backwards compatibility (that
everyone always loves to bash), I can declare dependencies on libraries
written in Java 1.1, and it will _JUST WORK_.

From what I understand, there's a fairly large chasm between Python 2/3 (such
that a lot of people use external libraries to deal with coding cross-
compatibile code, and apparently get wrong some-times).

------
jordanthoms
But if the tutorial didn't take 20 steps how would anyone know that it's Ready
For Enterprise?

~~~
hoodoof
That "hello world" project has now been incubated as an Apache Open Source
Project.

You can download and install Apache Hello World for Java Enterprise Edition on
an enterprise scale (assuming of course that you have sufficient bandwidth
remaining for this month).

Support is available for "Apache Hello World Enterprise Edition" from Tata
Consulting Services, HP Consulting Service and if that's not expensive enough
for you, Price Waterhouse are now offering dedicated fly-in-from-overseas
teams who have the skills and experience to roll out "Enterprise Hello World"
in record implementation time of generally less than 6 months, not including
customisations to your environment, which will be built by university
graduates at $1,200 per day.

Business Analysts are ready to write sophisticated UML diagrams to map out how
to integrate Apache Hello World in carefully considered ways that match your
business processes.

New Relic will provide application instrumentation for your Apache Hello World
implementation to ensure if (when?) it goes down you'll be able to rapidly
pinpoint the general 50,000 code lines area that the fault might lie.

~~~
daemonl
I love the way you have expressed this, kind of what I'm trying to get across
to people but can't quite put it into words.

Any interest in fleshing it out into a whole post?

------
codeonfire
SWF is a developer tar baby. Don't touch. It's incredibly complex for what
little it does. At the service side, a simple queue server would replace it.
Everything about the 'workflow' is implemented on the client using whatever
latest java abomination like AOP backed annotations.

~~~
AReallyGoodName
Author here. I thought that too at first. It's actually straightforward
though. I now have a video transcoding workflow that works well.

It's not SWF that's the problem. It's actually really straightforward to use.
AOP is not required, annotations are not required and those design patterns
are not required. It's just the really messed up documentation that makes you
think this.

Check the bottom of the above article. You just take the C# sample and copy
and paste it onto Java. Change the syntax to Java. It gets a bit more verbose
but is still trivial to grok.

~~~
optimusclimb
Did you contact support or email someone responsible for SWF in some way, or
just write the blog post?

~~~
AReallyGoodName
jcrites from Amazon has responded above in this thread which is nice.

------
pjlegato
Reasons why I stopped coding in Java: Set up 15 Eclipse plugins, download 23
jars, and then configure 57 XML files in order to write 'Hello, world'.

~~~
icedchai
"Enterprise" Java (app servers, etc.) sucks but there are light weight
alternatives (such as Dropwizard) that don't have the problems of 10+ years
ago. There's no XML garbage and there's minimal boilerplate.

And, as a bonus, with Java you get real threading, don't spend all day working
around single threaded interpreter GILs or dealing with call back hell. You
can actually use all the cores on those CPUs, in a single process if you want!

~~~
lostcolony
And then you find out pjlegato switched to Elixir, where he gets lightweight
libraries by default, real threading, no GILs, no callback hell, uses all the
cores trivially, in a single process, -and- gets a concurrency model that
doesn't suck, baked in distribution that doesn't suck, better VM
introspection, fault tolerance second to none, tail call optimization, soft
real time performance, higher order functions, and glorious, glorious pattern
matching.

Or maybe not, but just sayin', you're making assumptions in trying to defend
Java there. It's enough to say "You don't have to write Java that way", and
then find reasons why Java stands on its own ("It's the lingua franca of
software development", and related, is the best I can come up with, but eh),
rather than attacking a strawman by assuming what traits the language(s) he
switched to are and comparing Java against those.

~~~
didibus
I think pjlegato switched to Clojure, where you get pretty much everything you
mentioned there too. At least looking at his github commits.

~~~
lostcolony
There ya go then. Though, Clojure doesn't have most of those additional things
I listed either, as most of them are requirements of the VM rather than the
language (it does, however, have a slew of other things that make it awesome,
and it has the language level features I mentioned)

------
carsongross
Running a spark java app on heroku is pretty damned civilized, though:

[https://sparktutorials.github.io/2015/08/24/spark-
heroku.htm...](https://sparktutorials.github.io/2015/08/24/spark-heroku.html)

Friends don't let friends not let friends use java, if it's the right tool for
the job.

------
jasonjei
Overall, I've found a lot of the AWS documentation to be missing essential
information or examples, or vital bits scattered across the AWS web
properties. For example, setting up multi-instance Docker containers was not
trivial; essential IAM policies needed to get AWS to work were scattered in
marketing information. I think AWS has a great collection of products, but it
is definitely not turnkey.

------
scottjbarr
The sad part is a lot of enterprisey Java devs will looks at this, not see
anything disturbing, and go... "OK!"

------
suprgeek
The article headline captures the essence of the issue exactly right "the AWS
Java DOCUMENTATION is ...".

You can write Horrid examples in any Elegant Language and conversely you can
give elegant examples in Brainfuck. The person(s) writing the Java example
fell into the classic Java trap that mid-level Java folks fall into. Namely
that trying to follow SOLID while writing an "Hello World" Distributed Java
example.

They lost sight of the fact that the end product is supposed to be an EXAMPLE.
This is why the senior devs (Java or otherwise) make the big bucks. Not
because they can write complex hairy code but precisely because they
understand when NOT to do it (almost always - YAGNI).

------
mjmsmith
I'll just leave this here... [http://blog.marksmith.org/s-for-
simple/](http://blog.marksmith.org/s-for-simple/)

------
wanghq
I followed the same guide when I learned SWF and used it in a project. I
appreciated the detailed guide and was amazed by the flow framework. Because
of flow's magic and the steep learning curve, I believe SWF might be the most
underestimated AWS service. I agree that the java flow framework is
complicated but very powerful as well. Seems the ruby flow framework is
simpler to use
([http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/h...](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowguide/helloworld.html)).

------
joesmo
AWS documentation is by far the worst I've _ever_ seen. For all their
services. It's unsearchable (through Google or otherwise), most of it no
longer pertains and has been superseded but they won't tell you. It's split up
into many different places that are not linked together, so when you think
you've found your answer, you probably haven't. And of course, it never covers
the truly hard problems like all the bugs in their platform. Total and
absolute shit.

------
melted
I think it's an elaborate prank.

~~~
krapp
The tutorial or Java?

~~~
metaphorm
yes

------
sandGorgon
They should really be switching over to SparkJava - here's a quick article
from Twilio on how to build a webapp in Java in 10 lines using Java 8 and no
xml (hint: use gradle) [https://www.twilio.com/blog/2015/09/getting-started-
with-gra...](https://www.twilio.com/blog/2015/09/getting-started-with-gradle-
and-the-spark-framework-3.html)

------
miralabs
in Java you always have this.. Impl Impl Impl.. Impl everywhere. I feel it's
being passed from a senior and a junior dev who interprets the "program to an
interface" idiom. Its so annoying to follow a code that is deeply nested with
calls on a very basic controller call. It seems to be program to think that
calls will be dynamically "replaced" and "reloaded".

So much complexity in the Java world and I don't know if its because of the
language has not evolved throughout the years or the quality of developers
(majority) that it has produced. Reminds me of this
[https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpris...](https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpriseEdition)

We also have the same developers coding in javascript. I literally need to
refactor once a 7k+ lines single ExtJS controller. Yeah Extjs is so popular in
the enterprise java world.

~~~
manyxcxi
To be fair about Interfaces and implementations- when you're using DI and
Aspects, or really any type of framework that is going to be proxying your
classes it is a good idea to code to an Interface, even if you only have one
implementation.

I read a few great articles on this a long time ago and unfortunately I don't
have the references at hand, but it was compelling enough that I Interface
anything that's going to be proxied or injected.

That being said, I REFUSE to call anything an Impl. If I have an interface
called FileSavingService, I'll have a LocalFileSavingService or an
S3FileSavingService, but I'll chop my fingers off before I add Impl to the end
of them.

~~~
jrockway
I generally like coding things to interfaces, as you often implement the
interface twice; once for the real system, once for unit tests of other
dependent components. Not using interfaces leads to either compiling test code
into your production binary, or other more-horrifying hacks (mocks!).

------
KirinDave
I mean, to be fair the quality of the C# apis for AWS is also a lot better
than the Java apis. There are a few okay ones like the SQS library but...

It is not just the documentation.

Having recently been embedded into a very large corporation with a lot of
legacy tech platforms, I have to say I've heard people _praise_ the AWS Java
documentation, apis and design patterns.

Praise.

It worries me.

------
i336_
I'm not sure if this sort of thing is the done thing, but I flagged this
because I think the title may flag the front page on some work
proxies/filters/monitoring systems. The title just needs minor
redacting/editing, that's all.

Also - sorta-relevant discussion on the argument of Java being unnecessarily
verbose (possibly interesting parent thread too):
[https://news.ycombinator.com/item?id=10769322](https://news.ycombinator.com/item?id=10769322)

I've never used Java (not counting experimenting with Bluetooth in J2ME for
lulz), but I've head a lot of opinions and thoughts about it. I wonder if
(especially considering the parent thread off the above link) Java's tendency
to encourage AbstractSingletonProxyFactoryBeans (see:
[https://news.ycombinator.com/item?id=4549544](https://news.ycombinator.com/item?id=4549544))
is simply a way to fill developers' heads with so much indirection* that we
simply cannot grasp that it ultimately makes no difference.

* - indirection: my poor word to describe having to constantly resolve what something means, and cross-reference information, etc - stuff that swamps and/or overflows our mental stacks really quickly.

Of course, the above being said, the elements of the language _seem_ elegant -
patterns and models and the like providing us with "everything has a place and
everything in its place," if you will - and of course the encouragement in
exponential verbosity looks _really_ good in our progress reports.

~~~
kuschku
Java is easy to do right, and easy to do simple.

Until you ever start interfacing with enterprise libraries.

As a novice, you'll just decide not to interface with them. Then you decide to
build makros that make interfacing with them simpler, and then you build just
another abstraction over them, using the very same AbstractSingleFactoryBeans
that the library itself used.

The reason why Java managed to be usable by modders of Minecraft — kids who've
never seen code before — and enterprise people at the same time is that Java
gives you the tools to build all the abstractions in simple ways, inside the
language.

In other languages you build a small hack using the preprocessor, or even
decide to build a DSL. With Java, you just build an abstraction over the
existing things.

As a result, you have 20 years of abstractions right on top of each other.

~~~
i336_
Oh, okay then. TIL. I have to admit that I've not really looked into Java that
much, probably due to being tangled up in the opinions and rhetoric. Thanks
for this perspective.

I guess I need to explore the language further! (And ideally with moderation
and discipline, it would seem.)

------
vijayrawatsan
At-least this documentation forced you to setup a blog that you have been
waiting to setup. ;)

------
whalesalad
I made it about half way through when I realized I'd rather put a bullet in my
head. The JVM is pretty neat and Java has a huge ecosystem but it's misery
like this that I can't tolerate. Using it from within Clojure can make it
palatable.

------
shiftoutbox
To be honest; I was waiting for step 37: Now that you have entered hell , let
us introduce you to Lua . Java is evil. Java must die.

On the flip side

Erlang will die , rise from the dead and keep on ticking.

Mumm Astro Zombies from erlang space .

------
komaromy
I hope there's more coming from this blog.

------
jeffbarr
The SWF team at AWS is aware of this thread! Thanks for all of the
perspectives and feedback.

------
arisAlexis
I lost the link and after reading this specifically went back on HN to search
and star it. Omfg - lol

------
r1d1culous
Java and I are just friends!

------
agumonkey
Or just wait for a clojure / scala / kotlin wrapper ?

------
wookasz
If you think this is bad, try configuring AWS elasticsearch.

------
confiscate
You're not getting the point dude.

The person who wrote it probably gets measured on the amount of "work" he/she
produces.

The more detailed the tutorial, the more "work" he/she has accomplished, at
least according to the rules/processes internal to the department in Amazon.

The person writing the tutorial _has_ to make it extra complicated. Otherwise
she/he will lose her/his job because other documentation writers will do a
"better job" by writing more "detailed" tutorials.

~~~
Periodic
Another scary thought: What if the person thinks this is clever and admirable
code?

I think many of us spend a lot of time in our ecosystems and we might lose
sight of what's outside. If someone spent all their days writing complicated
Aspect-Oriented code then maybe to them this is just second nature and the
right way to do it. What if you wanted to add more features, after all?

I wouldn't go so far as to imagine perverse incentives from management. It
could just be a cultural bubble that the person works in or they could work in
a place where most problems are far more complex and these sorts of solutions
make sense.

It can be difficult to remember who your audience is, what they know and what
they need to be told.

------
matthewcford
Don't knock AOP till you try it..

disclosure; I have worked in past on AJDT/AspectJ

