<?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="use_cases">
	<title>ModeShape Use Cases</title>
	<para>There are lots of ways to use ModeShape in your own applications, but this chapter attempts to show some representative
		scenarios that take advantage of ModeShape's support for the JCR API as well as the federation, integration, and sequencing 
		capabilities.
	</para>
	<sect1 id="service_repository">
		<title>Service repository</title>
		<para>
			In a SOA environment, one important component is a service registry that provides versioned storage of all the artifacts
			that describe the services, their capabilities/restrictions, and the policies that surround them.  Service repositories
			contain information that define the services and their message models, ownership, availability, security requirements/abilities, auditing, 
			funding, monitoring, provisioning, provenance, usage, discovery mechanism, configuration, documentation, relationships
			to other services, classification taxonomies, ontologies, and many other important aspects.
		</para>
		<para>
			A JCR repository provides an excellent starting point for a service repository.  The ability to store a wide range of
			content, ranging from structured information to documents, means that a JCR repository can offer the flexibility
			to manage and organize the information while maintaining the ability to adapt the structure and schema as needs evolve
			over time.
		</para>
		<para>
			A service repository will contain lots of information represented in different forms, and it's important that the repository
			make it easy for users to quickly find what they need.  Organization of the information (probably in multiple hierarchies and with tags) 
			is important, but more important is the ability for users to use simple searching (or more advanced queries) to return ranked 
			results that match the criteria.	For search to be effective, it is important that the repository understand the different 
			kinds of artifacts that are uploaded and the information they contain.  
		</para>
		<para>
			JCR repositories are naturally searchable and queryable, but also can be used to integrate a taxonomy (or folksonomic tags) 
			with the content, allowing the same content to be presented in different hierarchical classifications. 
			But ModeShape capabilities also offer a great advantage, since any file that is uploaded can be automatically sequenced and processed 
			to extract information that's meaningful and useful but often locked up within the file.  For example, when a WSDL file is uploaded, 
			the appropriate	sequencer(s) process the file and extract and store in the repository the structured information describing the types, 
			message structures, operations, port types, bindings, and services found within the WSDL file.
			When an XML Schema Document is uploaded, ModeShape can do the same for the schema's complex and simple types, element and attribute 
			declarations, model groups, namespaces, imports, includes, annotations, etc.  And ModeShape can do the same for the various policy files,
			resource declarations, documentation, presentations, ontologies, etc.
		</para>
		<para>
			Integration with a management system can be done in a similar manner.  A ModeShape connector could access the management system
			to discover the servers and enable auto-discovery of the services, and "tag" the services' deployments with the lifecycle phase 
			(dev, test, production, etc.). Plus, ModeShape sequencers can automatically process the uploaded artifacts to extract a useful
			structured representation of their content, and can then store that additional information in the repository. So not only are
			the original artifacts stored in the repository, but a structured representation of their content is also stored. And all of
			it can be accessed, navigated, searched, and even updated.
		</para>
		<para>
			By using ModeShape, a service repository could manage the wide range of artifacts required in a SOA or web-oriented architecture,
			yet be able to present a unified view of all service information.
		</para>
	</sect1>
	<sect1 id="data_source_management">
		<title>Manage data sources and services</title>
		<para>
			Many enterprise environments include numerous databases and data services, yet there is often no single place where all
			these different assets are described or related.  A data source/service repository could provide information about the
			many databases running within the enterprise as well as their documentation, schema history, availability, usage policies,
			current users of the data (including applications, ETL processes, reporting), geographic deployments and synchronization, 
			and the provenance of the data.
		</para>
		<para>
			Some of this information may actually be defined or controlled within the data sources themselves or within other systems.
			For example, the DDL scripts used to migrate the database schemas are (hopefully) stored in a version control system,
			and the databases themselves have the ability to describe their current schemas.
		</para>
		<para>
			Using ModeShape, the repository could use a connector to the version control system to expose the scripts, as well as 
			connectors to the databases to expose (and cache) the current schema of the databases as structured content.  
			ModeShape sequencers can automatically process the uploaded assets and artifacts to extract a useful
			structured representation of their content, and can then store that additional information in the repository.
			Applications can access, search, navigate, and update all of this metadata about the databases and data services,
			all through a single JCR repository using a standard JCR API and without having to touch the underlying systems.
		</para>
		<para>
			However, the power of a data repository is really the ability to capture the relationships that otherwise were only captured
			in people's heads or trapped in documents spread throughout the network. A data repository can capture the policies that
			dictate how each data source should be used (which are for development purposes, or QA/testing purposes, or which are production,
			and how are they all related), and it can integrate with management systems to provide information about
			availability and deployment.  As web services are created to provide service-based access to the data in databases,
			the repository can be used to maintain the relationships between these <emphasis>data services</emphasis> and the underlying sources.
			Similarly, the repository can track how the databases are used by applications, ETL processes, and reports.
			All of this information is just content that can be stored within the same JCR repository.
		</para>
	</sect1>
	<sect1 id="configuration_repository">
		<title>Configuration repository</title>
		<para>
			Many applications and libraries have configuration files that allow the users (or developers) to dictate the setup and behavior.
			Often this involves multiple files in a specific structure on the file system.  Invalid or inopportune changes to these files
			sometimes corrupt the environment, but creating a more robust configuration management system is often way beyond the desired
			effort.
		</para>
		<para>
			An embedded ModeShape repository can provide a more formal and flexible configuration system with little effort.  JCR's
			event system allows the system to be notified when the configuration changes, and versioning can help guarantee the ability
			to revert back to a previous (valid) configuration.  ModeShape connectors can be used to integrate the files on the file system
			into the configuration system, keeping it natural for those wanting to view and change the configuration via the files.
			ModeShape sequencers can even process the configuration files to extract a more structured view of the system.
			And because ModeShape can used with a minimal footprint, it provides the ability to manage and version the configuration
			with little overhead.
		</para>
		<para>
			ModeShape can even be used to centralize the configuration definition for a clustered or distributed system.  In this mode,
			the configuration is managed in a central repository that is remotely accessible by the application.  When a process is started,
			it examines the repository and reads the content containing its configuration.  The application can monitor the configuration for
			changes so that it can modify itself and its components.  
			For larger deployments, a central "enterprise configuration" repository can house the configuration of different kinds of systems,
			and can even be managed and manipulated through JCR.
		</para>
		<para>
			As we'll see in the <link linkend="using_modeshape">next chapter</link>, this is actually the way in which ModeShape manages
			its own configuration.  In the embedded case, the configuration repository is simply a local (in-memory) repository that
			is populated by the configuration file (or programmatic API).  In a clustered mode, the repository can be centralized.  But either
			way, to ModeShape the configuration is always defined in a repository.
		</para>
	</sect1>
	<sect1 id="use_case_whats_next">
		<title>What's next</title>
		<para>
			The scenarios described in this chapter are representative of some of the ways in which ModeShape can be used, and hopefully
			give you ideas about how you can leverage ModeShape in your application or library.
		</para>
		<para>
			In the <link linkend="using_modeshape">next chapter</link>, we'll show how you can set up ModeShape and use it via the standard JCR API.
		</para>
	</sect1>
</chapter>
