Add non Spring-Boot powered guides

[mdeinum]

A couple of days ago this thread arose on StackOverflow. I think they have a point, although most of us like Spring Boot it would be nice to still have a couple of plain guides for Spring Framework (or related projects). Most projects still use plain Spring (with some of the portfolio projects) and not Spring Boot.

I think the current guides are great and really allow the reader to focus on the root content of the guide and not being distracted by the setup around that (datasources, connection factories etc.).

[martinjeannot]

I don't know if Brett Ryan is going to comment here on the issue but I have about the same point of view regarding this matter as he does. To sum his thoughts up : Spring should be a tool, not a foundation.

And I agree with that which doesn't mean Spring Boot isn't great, like I said it gets you started in seconds so it's a very useful tool to try some Spring modules without having to set up an entire project by hand for example. The thing is, while taking an opinionated view of the Spring platform, it also kind of takes an opinionated view about the way you are going to build your project.

But this is really not the place to argue about that, the issue was simply raised because some of us would like non Spring Boot guides so that we could get our hand dirty the official way. Obviously those tutorials would be extensive and I understand that it defeats the purpose the Getting Started or Quick Start current trend (as stated by @mdeinum people usually don't takes days to figure it out, if it doesn't work < 5m a guide/project/sample is crap even if the error is their own). Nevertheless, I still think some of us would appreciate.

[dsyer]

What makes anyone think Spring Boot is only for getting started, or that it isn't "official"? Simply put, neither is the case, and the sooner people start spreading that message the better. One of the primary goals of Spring Boot is to be opinionated, but it's not like Spring foundation projects are never opinionated. The difference is that Boot is able to provide default behaviours that suit most people quite well all the way to production. If you don't like those behaviours, you can simply add your own, without compromising.

I do think that the GS guides need some more meat behind them for anyone who wants to understand more about what they are doing (i.e. beyond the "getting started" experience). But that exercise (and the research that a user will do to satisfy that curiosity) can still be carried out within the framework of a Boot application. Why bother configuring stuff that you don't need to? I don't understand why anyone would these days.

[mdeinum]

@dsyer :+1:

I agree that Spring Boot is more then getting started (heck spring.io is using it as runtime) but I can also sympathize with the Spring starters not seeing the full picture when working with a technology (JPA, MongoDB). But that might also be solved with extending the current guides instead of adding new ones.

[brettryan]

@dsyer In an ideal world where everything is fairly straightforward, then yes, spring boot could be used from conception to production, but that's not necessarily the case for many of us, and certainly not for those thousands of projects using spring-foundation that aren't about to go and migrate to boot simply because it's the new way of doing things.

Likewise, there's still hundreds of us still using XML configuration over Java configuration, and again, many of us will not change because it may actually suit that project.

Some projects I've worked on and manage require quite complex configuration scenarios that aren't even catered for with standard spring, trying to get these types of scenarios to work with boot is much harder than one might imagine, and wasn't even possible with the first few iterations of Java based configuration. Consider a project with 9 different DB sources, multiple authentication sources, complex tiles view preparer configurations.

I totally agree with not wanting to configure something you don't need to, but some of us and I encourage most to know how something works to understand what can go wrong, or how to change the behaviour. With boot, I personally have no freakin' idea what's going on under the hood, how am I expected to know how to change the behaviour or understand what it's even doing? How can I trust it? I can trust core spring, I know how it works, I understand how to manipulate its behaviour, because there has been fantastic documentation and samples in the past.

Just a final closing comment, there used to be hundreds of spring source managed samples with XML configurations that are still applicable today, but have all been removed, where did they go?

[odrotbohm]

I can see where @mdeinum is coming from, but let's be reminded that these guides are what the name suggests: getting started guides. That's what they are and what they should continue to be IMO. A getting started guide on transaction management for JPA sets you up to get started with it but cannot (I'd argue: must not) cover all options that you have with Spring regarding the transaction management setup.

I think we can do a better job on presenting pointers to the more detailed sections on a particular topic in the guides. But even here I'd argue they should be in a sidebar and not disturb the reading flow of the guide. Because of one main reason: it distracts from the main focus of the target audience - to get started with X. That's why we just deployed the folding of the build instructions by the way. The Spring reference documentation will undergo a significant overhaul for the upcoming minor release, so that might as well play into that story.

I also think that we can improve the tutorials we have by quite a bit as they open up room for more in depth discussion and can cover much more options. Still, I think also those should be on Boot. Think of Boot as the primary access point for Spring developers these days. It's not a side project of any kind. It's simply the one and best way to build Spring applications as of today. Why would you want to start more complex than necessary on a new project? If it's about ramping up new developers on brown-field projects, you need to do that in a very specific way to all the decisions you made anyway. There's no generic solution to this as there are so many different projects out there.

And - speaking of complexity:

… a project with 9 different DB sources, multiple authentication sources, complex tiles view preparer configurations.

This is not complexity Boot will manage for you, nor will any other technology do. That's inherent complexity to the project. And that's by far nothing any guide could cover. Boot covers the accidental complexity introduced by the technology stack chosen for the solutions space.

[gregturn]

For those that wonder what Boot is doing, please read http://docs.spring.io/spring-boot/docs/1.1.6.RELEASE/reference/htmlsingle/#howto-troubleshoot-auto-configuration. It introduces you to the autoconfiguration report. This report is injected into the app context and can also be read from an actuator endpoint as well as dumped out to the console. It's not all black magic completely hidden from you.

And +1 to Dave's point. Boot isn't just for POC apps and marketing demos. It was designed from the beginning for production grade apps.

[brettryan]

@olivergierke I wasn't suggesting boot or the guides should handle it, I was arguing that it's difficult to read a boot centric tutorial, and integrate that into an existing project that isn't using boot. Sure, you get the main point across with boot, but nobody understands what plumbing work boot is actually doing. As of today, I can not fully migrate to Java based config as some aspects just aren't possible let alone migrate to boot, and I probably never will.

I totally get that boot is for production grade, but many are missing the point that the guides also need to target existing customers, not just new ones.

A good start would be to bring back the old guides and put them in a legacy section?

Here's a question, can boot do everything that a standard XML configured spring stack environment can do? And I mean everything? AFAIK Spring-security can't handle all cases with Java config yet.

[brettryan]

@gregturn Thanks for the link, will need to study this document, I was looking for answers in the spring-framework documentation.

[odrotbohm]

@brettryan Re: XML-Config - yes, just use @ImportResource on the Boot main class to import all your XML config and off you go :).

Re: Guides for existing users - the issue I see here is where should we start and where should we end? Right now it's pretty easy: with the guides, we make sure you find decent resource about state-of-the art Spring development easily. For everything else, there's already tons of material out there. Ironically that became a problem, as people were finding the legacy samples when they were looking for new stuff.

[gregturn]

Something else that is under discussion is link aggregation. The Spring portfolio has lots of examples spread across the various projects. There is benefit in keeping this stuff underneath existing projects, because they can be tested with various releases.

Link aggregation would empower a project leader to "publish" a subset of examples (possibly with filterable metadata) to also appear underneath spring.io/guides, perhaps under a separate section. Naturally, we have to think about the dev's experience and balance that against ease-to-publish-and-maintain on behalf of the lead. We can't shift the whole team into content curation or nothing will move forward. But serving up existing samples might be quite handy.

[brettryan]

Thanks @olivergierke I think if the guides for boot had a section on what dependencies they are obtaining and possibly a section on core beans being auto configured it would go a long way, especially when one wants to override the configuration, you need to know what was going on in the autoconf before you can override it.

The other side is how invasive boot is to the build cycle, parent poms, boot specific compiler.

[brettryan]

What about this for a compromise.

If spring is pushing boot for a whole project stack and provides all guides using boot, that means core spring-framwork has no guides, but the reference documentation is great for it, just very verbose.

What if, for each guide, the relevant reference documentation for that guide article is linked, with a section "if you're not using boot, you're on you're own, but here's the information to get you started and apply this article" which has a series of links to the core framework reference documentation.

I'd be happy with that.

[gregturn]

@brettryan I agree that having guides link back to key ref doc parts, no matter where, would be the right thing to do. It would also help SEO in general, right? The more links to "current" ref docs would increase your odds of finding a link via Google to either a guide OR its supporting links. (If I know ANYTHING about SEO).

Something @dsyer discussed briefly at SpringOne was that people need to "getting started" experience as it is, but then have the avenue to start exploring. We hit on the subject of ensuring at least one automated test was added to each guide that pokes at the focal point of the guide. This would give the reader something to alter and tweak. Still not sure how easy or hard that will be to curate and not have it overwhelm my schedule.

[brettryan]

Perfect, specific links under http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/ for core spring components and links to the other relevant projects reference would do wonders so we don't have to hunt through it all.

I understand it might be a bit of work, and I'd certainly offer to help, but if I can't yet understand what boot is doing I'm probably not the best person to put my hand up.

Knowing spring != knowing boot

[dsyer]

Adding links to project documentation is absolutely necessary, and part of the solution to the "what to do next" problem. If it makes everyone in this thread happy then I think we have a plan. All the guides already have a "Projects" link set, and a "Technologies" link set. I guess the former is the right place to put the new links - they are just more granular versions of what is there already. Should have been there from the start really, but I guess there was always time pressure to get more guides done, so I can understand why they weren't.

I think having some tests, or even one test, the adding of which could be automated to a degree, is also a good idea.

[brettryan]

@dsyer Sure thing, that would be excellent, could a third "Reference Documentation" heading be added?

I also agree with the tests, as long as those tests adhere to the spring testing conventions, unless clearly stated that the test is not the norm.

The Designing and Implementing a Web Application with Spring tutorial does make good use of explaining how to test the core focus of the article.

[rwinch]

AFAIK Spring-security can't handle all cases with Java config yet.

@brettryan Can you please elaborate on this statement? You should be able to do anything with JavaConfig you can do with the XML based configuration (some of the ways are a bit different though).

[brettryan]

Sorry for the late reply rwinch, have been unwell and just getting back to normal.

I've never been able to figure out how to configure multiple <security:http> representations within Java config. Consider the following configuration that might be used to secure two different components of the application I've created this question on SO in the hopes of finding an answer, if you know how to answer please answer there so I can accept it.

<security:http pattern="/api/**"
               create-session="never"
               use-expressions="true">
  <security:http-basic entry-point-ref="xBasicAuthenticationEntryPoint"/>
  <security:session-management />
  <security:intercept-url pattern="/tests/**" access="isAuthenticated()"/>
  <security:intercept-url pattern="/api/**" access="isAuthenticated()"/>
</security:http>

<security:http auto-config="true" use-expressions="true" realm="ACME">
  <security:intercept-url pattern="/favicon.ico" access="permitAll" />
  <security:intercept-url pattern="/static/**" access="permitAll"/>
  <security:intercept-url pattern="/error/**" access="permitAll" />
  <security:intercept-url pattern="/" access="permitAll"/>
  <security:intercept-url pattern="/login" access="permitAll"/>
  <security:intercept-url pattern="/logout" access="isAuthenticated()"/>
  <security:form-login login-page='/login'
                       authentication-failure-url="/login?error"/>
  <security:logout logout-url="/logout" logout-success-url="/"/>
</security:http>

This allows the configuration of /api/** to use the authentication from the session if available but will not redirect to the login form.

How would this be achieved throughout Java config? I've tried various approaches, namely creating multiple WebSecurityConfigurerAdapter instances with @Order annotations to control the rest one first, doing this just seemed to turn off authentication altogether.

It could be that I'm just too comfortable with XML config, but I've tried many times to migrate and I just seem it more verbose and keep falling back to XML config.

[brettryan]

Oh far out, I've just found it in the docs how to do this. I am sure I couldn't find that in the past, was this a fairly new thing, maybe? Sorry.

[gregturn]

Seeing no plans to write extra guides that are explicitly non-Boot, I am closing this issue.

[brettryan]

What happened to adding reference doc links to the pages relevant to the article? Existing articles do not have reference document links to the relevant pages, just to the project page. We need reference documentation links to provide more extensive support on the components within each guide.

[gregturn]

That idea is still in place. We just aren't necessarily going guide by guide right now. But don't forget, many of these guides do have links. For example, https://spring.io/guides/gs/scheduling-tasks has links to pertinent javadocs on configuring the scheduling annotations.

[brettryan]

Excellent. I was thinking more so about linking back to the actual reference documentation which is a fantastic set of docs but can be overwhelming for someone getting started. Links directly to the reference docs (not so much the API docs) are a necessity.

On 3 Apr 2015, at 04:50, Greg Turnquist notifications@github.com wrote:

That idea is still in place. We just aren't necessarily going guide by guide right now. But don't forget, many of these guides do have links. For example, https://spring.io/guides/gs/scheduling-tasks has links to pertinent javadocs on configuring the scheduling annotations.

— Reply to this email directly or view it on GitHub.

[gregturn]

@brettryan Sure thing. I guess if people open issues in key places, it is easier to track down.