svn commit: r1459863 - in /jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate: SessionDelegate.java package-info.java

[md...@apache.org]

Author: mduerig
Date: Fri Mar 22 16:00:46 2013
New Revision: 1459863

URL: http://svn.apache.org/r1459863
Log:
OAK-672: Avoid JCR APIs calling other JCR APIs
- Initial version for the documentation of the JCR API vs. delegates contract

Added:
    jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java   (with props)
Modified:
    jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/SessionDelegate.java

Modified: jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/SessionDelegate.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/SessionDelegate.java?rev=1459863&r1=1459862&r2=1459863&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/SessionDelegate.java (original)
+++ jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/SessionDelegate.java Fri Mar 22 16:00:46 2013
@@ -16,6 +16,8 @@
  */
 package org.apache.jackrabbit.oak.jcr.delegate;
 
+import static com.google.common.base.Preconditions.checkNotNull;
+
 import java.io.IOException;
 
 import javax.annotation.CheckForNull;
@@ -36,27 +38,8 @@ import org.apache.jackrabbit.oak.core.Id
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import static com.google.common.base.Preconditions.checkNotNull;
-
 /**
  * TODO document
- *
- *
- * Responsibilities of JCR Impl classes:
- * * name/path mapping for both method arguments and return values
- * ** NamePathMapper should be in SessionImpl instead of SessionDelegate
- * * tracking and instantiation of other JCR Impl objects
- * ** Delegate classes should refer to neither the JCR API nor the Impl classes
- * ** Values should be returned as PropertyState instances that are mapped to JCR Values by an Impl class
- *
- * Delegate classes
- * * access to the Oak API
- * * the checkStatus() and perform() logic
- * ** Something like:
- * *** all the "business logic" associated with complex operations
- * *** the complex SessionObject classes from Impl classes should be pushed down to Delegates
- * *** dlg.perform(dlg.getSomeOperation(oakName, ...))
- *
  */
 public class SessionDelegate {
     static final Logger log = LoggerFactory.getLogger(SessionDelegate.class);

Added: jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java?rev=1459863&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java (added)
+++ jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java Fri Mar 22 16:00:46 2013
@@ -0,0 +1,47 @@
+/*
+ * 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.
+ */
+
+/**
+ * This package contains the delegates for the various JCR API entities.
+ * While the JCR API implementation classes directly implement the client
+ * facing JCR API, they do so without implementing much of the business
+ * logic themselves but rather rely on the functionality provided by the
+ * delegates. This separation of the JCR functionality into external and
+ * internal variants guarantees that JCR API consumers cannot gain access
+ * to internals by simply casting to an implementation class. Further it
+ * makes internal round-tripping through the JCR API unnecessary since
+ * all functionality is provided by the internal interface (i.e. delegates),
+ * which simplifies maintaining and checking state invariants.<p/>
+ *
+ * <b>Responsibilities of JCR API implementation classes:</b>
+ * <ul>
+ * <li>Prevent access to internals.</li>
+ * <li>Name/path mapping for both method arguments and return values.</li>
+ * <li>Tracking and instantiation of other JCR implementation objects.</li>
+ * <li>Conversion from JCR Values to PropertyState instances and vice versa.</li>
+ * <li>No direct access to the Oak API</li>
+ * </ul>
+ *
+ * <b>Responsibilities of the delegate classes:</b>
+ * <ul>
+ * <li>Business logic associated with complex JCR operations.</li>
+ * <li>Provide means for state invariant checking.</li>
+ * <li>Must no refer to neither the JCR API nor its implementation classes.</li>
+ * </ul>
+ */
+package org.apache.jackrabbit.oak.jcr.delegate;
+

Propchange: jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/package-info.java
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision Rev URL