You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by cs...@apache.org on 2007/02/07 22:30:43 UTC
svn commit: r504701 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs:
controls/index.xml controls/serialization.xml site.xml
system-controls/jdbc/guide.xml
Author: cschoett
Date: Wed Feb 7 13:30:43 2007
New Revision: 504701
URL: http://svn.apache.org/viewvc?view=rev&rev=504701
Log:
Doc work for BEEHIVE-558, created new control's doc which details controls serialization.
Also removed old JDBC system control guide which is no longer referenced.
Added:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/serialization.xml (with props)
Removed:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/system-controls/jdbc/guide.xml
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/index.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/index.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/index.xml?view=diff&rev=504701&r1=504700&r2=504701
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/index.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/index.xml Wed Feb 7 13:30:43 2007
@@ -12,6 +12,7 @@
<li><a href="site:docs/controls/overview">Controls Overview</a></li>
<li><a href="site:docs/controls/programming">Control Programming</a></li>
<li><a href="site:docs/controls/containment">Control Containment</a></li>
+ <li><a href="site:docs/controls/serialization">Control Serialization</a></li>
</ul>
<p>
The following <strong>project template</strong> will help you get a Control project started:
Added: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/serialization.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/serialization.xml?view=auto&rev=504701
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/serialization.xml (added)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/serialization.xml Wed Feb 7 13:30:43 2007
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+
+ $Header:$
+ -->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Control Serialization</title>
+ </header>
+ <body>
+ <section id="overview">
+ <title>Overview</title>
+ <p>
+ This document describes what happens when a control is serialized by its runtime container. All controls
+ are serializable by default but may be marked as transient if containing state which does not need
+ to be serialized.
+ </p>
+ </section>
+ <section id="istransient">
+ <title>isTransient</title>
+ <p>
+ When developing a control which does not need its state serialized, the isTransient attribute of the
+ ControlImplementation annotation may be set to true. If not explicitly set isTransient will default
+ to false.
+ </p>
+ <source>
+@ControlImplementation(isTransient=true)
+public class MyControlImpl implements MyControl {
+ .
+ .
+ .
+}
+ </source>
+
+ <p>
+ If isTransient is set to true the control implementation will not be serialized. After deserialization
+ a new instance of the control implementation will be instantiated by the controls framework upon the
+ first method invocation on that control.
+ </p>
+ </section>
+
+ <section id="xmlvsjava">
+ <title>XML vs Java Serialization</title>
+ <p>
+ Beehive controls support standard Java serialization as well as XML serialization. All of the necessary
+ java.beans.PersistenceDelegate implementations already exist in the controls framework to support XML
+ serialization via the java.beans.XMLEncoder/java.beans.XMLDecoder classes.
+ </p>
+ </section>
+
+ <section id="walkthrough">
+ <title>Serialization Steps</title>
+ <p>
+ Before serialization can occur, the current ResourceContext must be ended for all controls within the
+ ControlContainerContext (CCC). Typically this is accomplished by a call to the CCC's endContext()
+ method. The endContext() method causes an onRelease resource event to be fired to all controls within
+ the CCC. Controls with onRelease event listeners then have the opportunity to release any resources
+ (such as JDBC connections, JNDI contexts, sessions, etc) before serialization.
+ </p>
+
+ <p>
+ When deserialization occurs these resources can then be re-acquired by the control after a new
+ ResourceContext has been established by the CCC and each control is notified with on onAcquire
+ resource event.
+ </p>
+
+ <p>
+ The CCC performs a number of actions on serialization:
+ </p>
+
+ <ol>
+ <li>
+ Service providers (java.beans.beancontext.BeanContextServiceProvider) registered with the
+ ControlBeanContextServicesSupport instance are serlialized, including any registered
+ ServiceProviderListeners which have been registered for those services.
+ </li>
+ <li>
+ Next the children of the CCC are serialized. Children include ControlBeans as well as each
+ ControlBean's ControlBeanContext. Any registered BeanContextMembershipListeners are also
+ serialized at this point.
+ </li>
+ <li>
+ Each ControlBean contains a reference to a control implementation class which gets serialized
+ at this point as well (unless the implementation's isTransient annotation attribute is set
+ to true, which case it will not be serialized).
+ </li>
+ <li>
+ The control's property state gets serialized at this point as well.
+ </li>
+ </ol>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/serialization.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml?view=diff&rev=504701&r1=504700&r2=504701
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/site.xml Wed Feb 7 13:30:43 2007
@@ -121,6 +121,7 @@
<resource_lf href="#Resource+Events"/>
</programming>
<containment label="Container" href="controls/containment.html"/>
+ <serialization label="Serialization" href="controls/serialization.html"/>
<testing label="Testing" href="controls/testing.html"/>
<projects label="Project Model" href="controls/projects.html"/>
<tutorial label="Tutorial" href="controls/tutorial.html"/>