<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../custom.dtd">
%CustomDTD;
]>
<chapter id="introduction">
  <title>Introduction</title>
  <para>There are a lot of ways for applications to store information persistently so that it can be accessed at a
    later time and by other processes. The challenge developers face is how to use an approach that most closely matches the
    needs of their application. This choice becomes more important as developers choose to focus their efforts on
    application-specific logic, delegating much of the responsibilities for persistence to libraries and frameworks.</para>
  <para>
    Perhaps one of the easiest techniques is to simply store information in
    <emphasis>files</emphasis>
    . The Java language makes working with files relatively easy, but Java really doesn't provide many bells and whistles. So
    using files is an easy choice when the information is either not complicated (for example property files), or when users may
    need to read or change the information outside of the application (for example log files or configuration files). But using
    files to persist information becomes more difficult as the information becomes more complex, as the volume of it increases,
    or if it needs to be accessed by multiple processes. For these situations, other techniques often have more benefits.
  </para>
  <para>
    Another technique built into the Java language is
    <emphasis>Java serialization</emphasis>
    , which is capable of persisting the state of an object graph so that it can be read back in at a later time. However, Java
    serialization can quickly become tricky if the classes are changed, and so it's beneficial usually when the information is
    persisted for a very short period of time. For example, serialization is sometimes used to send an object graph from one
    process to another.  Using serialization for longer-term storage of information is far less useful.
  </para>
  <para>
    One of the more popular and widely-used persistence technologies is the <emphasis>relational database</emphasis>. 
		Relational database management systems have been around for decades and are very capable. The Java Database Connectivity
    (JDBC) API provides a standard interface for connecting to and interacting with relational databases. However, it is a
    low-level API that requires a lot of code to use correctly, and it still doesn't abstract away the DBMS-specific SQL
    grammar. Also, working with relational data in an object-oriented language can feel somewhat unnatural, so many developers
    map this data to classes that fit much more cleanly into their application. The problem is that manually creating this
    mapping layer requires a lot of repetitive and non-trivial JDBC code.
  </para>
  <para>
    <emphasis>Object-relational mapping</emphasis>
    libraries automate the creation of this mapping layer and result in far less code that is much more maintainable with
    performance that is often as good as (if not better than) handwritten JDBC code. The
    <ulink url="http://java.sun.com/developer/technicalArticles/J2EE/jpa/">Java Persistence API (JPA)</ulink>
    provide a standard mechanism for defining the mappings (through annotations) and working with these entity objects. Several
    commercial and open-source libraries implement JPA, and some even offer additional capabilities and features that go beyond
    JPA. For example, <ulink url="http://www.hibernate.org">Hibernate</ulink> is one of the most feature-rich JPA implementations
		and offers object caching, statement caching, extra association
    mappings, and other features that help to improve performance and usefulness.  Plus, Hibernate is open-source (with support
		offered by <ulink url="http://www.jboss.com">JBoss</ulink>).
  </para>
  <para>
    While relational databases and JPA are solutions that work well for many applications, they are more limited in cases when the
    information structure is highly flexible, the structure is not known <emphasis>a priori</emphasis>, or that structure is
 		subject to frequent change and customization. In these situations, <emphasis>content repositories</emphasis>
    may offer a better choice for persistence. Content repositories offer the storage capabilities of
 		relational databases with the flexibility offered by other systems, such as using files.  Content repositories also
    typically provide other capabilities as well, including hierarchical organization, versioning, indexing, search, access control,
    transactions, and observation. Content repositories are often used by content management systems (CMS), document
    management systems (DMS), and other applications that manage electronic files (e.g., documents, images, multi-media, web
    content, etc.) and metadata associated with them (e.g., author, date, status, security information, etc.). The
    <ulink url="http://www.jcp.org/en/jsr/detail?id=170">Content Repository for Java technology API</ulink>
    provides a standard Java API for working with content repositories. Abbreviated "JCR", this API was developed as part of the
    Java Community Process under <ulink url="http://www.jcp.org/en/jsr/detail?id=170">JSR-170</ulink>
    and has been revised under <ulink url="http://www.jcp.org/en/jsr/detail?id=283">JSR-283</ulink>.
  </para>
  <para>
	  The JCR API provides a number of information services that are needed by many applications,
	  including: read and write access to information; the ability to structure information in a hierarchical and flexible manner that can adapt
	  and evolve over time; ability to work with unstructured content; ability to (transparently) handle large strings; 
	  notifications of changes in the information; search and query; versioning of information; access control; integrity constraints;
	  participation within distributed transactions; explicit locking of content; and of course persistence.
	</para>
	<figure id="jcr-features">
		<title>JCR API features</title>
		<graphic align="center" scale="100" fileref="jcr-features.png"/>
	</figure>
	<sect1 id="what_is_jboss_modeshape">
		<title>ModeShape</title>
		<para>
			What makes JCR interesting, however, is that a JCR implementation provides all these features and capabilities without exposing
			where or how that information is stored.  While other JCR implementations embed their own persistence technology, JCR becomes
			really interesting when it is used on top of existing information. <emphasis>This is in fact the main purpose of ModeShape:
			provide a JCR implementation that provides access to content stored in many different kinds of systems, including the federation
			of multiple systems.</emphasis>  A ModeShape repository isn't yet another silo of information, but rather it's a JCR view of the 
			information you already have in your environment: files systems, databases, other repositories, services, applications, etc. 
			<emphasis role="strong">ModeShape can help you understand the systems and information you already have, through a standard Java API.</emphasis>
		</para>
		<para>
			Of course when you start providing a unified view of all this information, you start recognizing the need to store more
			information, including metadata about and relationships between the existing content.  ModeShape lets you do this, too.
			And ModeShape even tries to help you discover more about the information you already have, especially the
			information wrapped up in the kinds of files often found in enterprise systems: service definitions, policy files,
			images, media, documents, presentations, application components, reusable libraries, configuration files,
			application installations, databases schemas, management scripts, and so on.  As files are loaded into the repository,
			ModeShape can <emphasis>sequence</emphasis> these files to extract from their content meaningful information that
			can be stored in the repository, where your applications can find it by using the standard JCR API to search,
			access, and use the information.
		</para>
		<para>
			So, ModeShape <emphasis>is</emphasis> a JCR 2.0 implementation that can be used as a traditional self-contained repository.
			But ModeShape can do so much more. It can automatically sequence files loaded into the repository, making it easier to reuse
			that information. It also lets your applications use the JCR API to access the content in other systems, and can unify the 
			content from multiple external systems and multiple storage systems to provide a single, federated repository.
		</para>
	</sect1>
	<sect1 id="introduction_whats_next">
		<title>What's next</title>
		<para>
			As we'll see in the <link linkend="use_cases">next chapter</link>, the ability of ModeShape to 
			federate, integrate, and sequence information make ModeShape a powerful asset and tool.  
			Then <link linkend="using_modeshape">Chapter 3</link> will show that once a ModeShape repository is set up, applications see
			ModeShape just as another JCR <code>javax.jcr.Repository</code> instance and use the standard JCR API to obtain a <code>javax.jcr.Session</code>
			and work with the content.
		</para>
		<para>
			<link linkend="downloading_and_building">Chapter 4</link> walks you through downloading
			and building the ModeShape examples, while <link linkend="sequencer_example">Chapter 5</link>
			and <link linkend="repository_example">Chapter 6</link> will run these very simple examples and walk through their code.  
			<link linkend="conclusion">Chapter 7</link> wraps things up with a discussion about the future of ModeShape
			and what you can do next to start using ModeShape in your own applications.
	  </para>
	</sect1>
</chapter>
