docs/reference/src/preface.xml

<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~     http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->
<preface>
    <title>Preface</title>

    <para>
        Securing a software application is a task that is almost always a necessity, but isn't
        something that we like to worry about very often. We're more focused on programming business logic,
        deadlines, performance, and many other things that are more directly related to things clients
        can see. Application security is often an afterthought and something that we do when we
        <quote>get around to it</quote>.
    </para>

    <para>
        While application security is usually a necessity, it would be nice if we could implement it whenever
        we want, and without it being too difficult. Actually, it
        <emphasis>shouldn't</emphasis>
        be difficult.
        In fact, it
        <emphasis>should</emphasis>
        be downright easy. It should also be as transparent and
        unintrusive as possible, so you don't have to change a lot of code to secure what you want.
        And above all, it should be extremely easy to understand, so when you do actually have to look at security
        code, it just makes sense.
    </para>

    <para>
        JSecurity is a Java security framework that attempts to achieve these goals. The framework tries to
        give as much power and flexibility as possible, while still being
        <emphasis>really</emphasis>
        easy to understand and easy to use. It tries to be the most comprehensive and feature-rich security
        framework in the Java world so that you have everything you need at your fingertips.
    </para>

    <para>
        This document is the official refrence manual for the JSecurity framework, and it aims to give you the
        most complete documentation on JSecurity and all of its features. It is
        very much a work-in-progress, and we welcome suggestions and recommendations. If you have any,
        we'd very much appreciate your feedback on our forums at
        <ulink url="http://www.jsecurity.org/forum">http://www.jsecurity.org/forum</ulink>
        or
        mailing lists at
        <ulink url="http://www.jsecurity.org/mailinglists">http://www.jsecurity.org/mailinglists</ulink>
        .
    </para>

    <para>
        Before continuing on, we'd like to give credit where it is due for the format of this
        book. We sincerely appreciate all the work that Christian Bauer from the
        <ulink url="http://www.hibernate.org">Hibernate</ulink>
        team and
        Juergen Hoeller of the
        <ulink url="http://www.springframework.org">Spring</ulink>
        team did in ensuring this
        document could be created in PDF and HTML formats. Without their efforts, it would have been an agnoizing
        task for us to do ourselves.
        Thank you!
    </para>

    <para>
        So, without further adieu, let's move on to the documentation. Feel
        free knowing you can incorporate JSecurity's rich features quickly and easily now, or perhaps maybe
        later when you<quote>get around to it</quote>.
    </para>

</preface>