<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-983C5DB9-85EF-541E-B494-19E3E617914A" xml:lang="en"><title>Introduction

to embedded stores </title><shortdesc>Data contained in a stream can represent a store in its own right

rather than just objects. Such a store is known as an embedded store.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The stream containing the embedded store is known as the host stream.</p>

<p>It is often convenient, and sometimes necessary, to collect the streams

representing a partial object network into an embedded store. This makes it

easier for the streams representing such a partial object network to be deleted,

by deleting (from the top level store) the stream containing the embedded

store.</p>

<p> The alternative is to traverse the individual streams representing the

partial object network and deleting them in the correct sequence; this can

be difficult.</p>

<p>The following diagram shows the idea:</p>

<fig id="GUID-612A6C2C-D706-50BB-A6C4-F2B5639685F8">

<title>Embedded store within stream</title>

<image href="GUID-8B1C7778-0C6D-5DEE-90FD-3B016EC0E3CE_d0e355357_href.png" placement="inline"/>

</fig>

<p>An embedded store can contain an arbitrarily complex network of streams.

As well as being easy to delete, this stream network can also be copied by

simply copying the host stream from the containing store.</p>

<p>Embedded stores are persistent stores.</p>

<p>The embedded store is constructed on a write stream in its containing store

and, for writing, the embedded store behaves like a direct file store — once

streams within the embedded store have been committed and closed, they cannot

subsequently be changed, i.e. streams cannot be replaced, deleted, extended

or changed in any way.</p>

<p>Embedded stores are used for object embedding by the application architecture.

Because the embedded store behaves like a direct file store, only document

types with direct representations can be embedded. In particular, documents

using permanent-type stores, such as the database or the agenda, cannot be

embedded. Such documents may, however, contain any type of embeddable document.</p>

<section id="GUID-72E3A832-7DE7-41F0-B021-BC37C6BB40DF"><title>See also</title> <p><xref href="GUID-C9D8D913-C65F-5A69-A606-30F59BFB38E2.dita">File stores</xref> </p> <p><xref href="GUID-B683496C-652E-5F48-924E-52D2FF3A78A7.dita">Direct file store</xref> </p> </section>

</conbody></concept>