Author: angela
Date: Thu Oct 24 12:25:29 2013
New Revision: 1535349
URL: http://svn.apache.org/r1535349
Log:
OAK-301 Document Oak : move 'known issues' to a separate page
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/known_issues.md
- copied, changed from r1534983,
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
jackrabbit/oak/trunk/oak-doc/src/site/site.xml
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md?rev=1535349&r1=1535348&r2=1535349&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md Thu Oct 24
12:25:29 2013
@@ -115,7 +115,9 @@ Observation
a subtree and replacing it with the same subtree will not generate any
event.
* Removing a referenceable node and adding it again will result in a
`PROPERTY_CHANGED` event for
- `jcr:uuid`.
+ `jcr:uuid`; the same applies for other built-in protected and mandatory
properties
+ such as e.g. jcr:versionHistory if the corresponding versionable node
+ was removed and a versionable node with the same name is being created.
* The sequence of differences Oak generates observation events from is
guaranteed to contain the
before and after states of all cluster local changes. This guarantee does
not hold for cluster
@@ -189,58 +191,4 @@ Principal Management
--------------------
Refer to [OAK-909](https://issues.apache.org/jira/browse/OAK-909) for a
general overview of changes
-with respect to Jackrabbit 2.
-
-Known issues
-============
-All known issues are listed in the Apache
[JIRA](https://issues.apache.org/jira/browse/OAK).
-Changes with respect to Jackrabbit-core are collected in [OAK-14]
-(https://issues.apache.org/jira/browse/OAK-14) and its sub-tasks.
-
-* Locking:
- * Locking and unlocking of nodes is not implemented yet. You will not see
an exception as long as
- the [TODO](https://issues.apache.org/jira/browse/OAK-193)-flag prevents
the implementation from
- throwing UnsupportedOperationException, but the node *will not* be
locked.
- See [OAK-150](https://issues.apache.org/jira/browse/OAK-150)
-
-
-* Versioning [OAK-168](https://issues.apache.org/jira/browse/OAK-168):
- * `VersionHistory#removeVersion()` is not implemented yet
- * `VersionManager#merge()` is not implemented yet
- * `VersionManager#restore()` with version-array is not implemented yet
- * Activities are not implemented
- * Configurations are not implemented
-
-
-* Query:
- * Known issue with OR statements in full text queries
- See [OAK-902](https://issues.apache.org/jira/browse/OAK-902)
-
-
-* Workspace Operations:
- * Cross workspace operations are not implemented yet
- See [OAK-916](https://issues.apache.org/jira/browse/OAK-916)
- * Workspace Management (creating/deleting workspaces) is not implemented
yet
- See [OAK-916](https://issues.apache.org/jira/browse/OAK-916)
- * `Workspace#copy()` is not properly implemented
- See [OAK-917](https://issues.apache.org/jira/browse/OAK-917) and sub
tasks
- * copy of versionable nodes does not create new version history
- See [OAK-918](https://issues.apache.org/jira/browse/OAK-918)
- * copy of locked nodes does not remove the lock
- See [OAK-919](https://issues.apache.org/jira/browse/OAK-919)
- * copy of trees with limited read access
- See [OAK-920](https://issues.apache.org/jira/browse/OAK-920)
-
-
-* Access Control Management and Permissions:
- * Move operations are not properly handled wrt. permissions
- See [OAK-710](https://issues.apache.org/jira/browse/OAK-710)
-
-
-* User Management:
- * Group membership stored in tree structure is not yet implemented
- See [OAK-482](https://issues.apache.org/jira/browse/OAK-482)
-
-
-In some cases Oak throws Runtime exceptions instead of a properly typed
exception. We are working
-on correcting this. Please do not work around this by adapting catch clauses
in your application.
+with respect to Jackrabbit 2.
\ No newline at end of file
Copied: jackrabbit/oak/trunk/oak-doc/src/site/markdown/known_issues.md (from
r1534983, jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md)
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/known_issues.md?p2=jackrabbit/oak/trunk/oak-doc/src/site/markdown/known_issues.md&p1=jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md&r1=1534983&r2=1535349&rev=1535349&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/known_issues.md Thu Oct 24
12:25:29 2013
@@ -15,162 +15,6 @@
limitations under the License.
-->
-Backward compatibility
-======================
-
-Oak implements the JCR API and we expect most applications to work out of the
box. However, the Oak
-code base is very young and not yet on par with Jackrabbit 2. Some of the more
obscure parts of JCR
-are not (yet) implemented. If you encounter a problem running your application
on Oak, please cross
-check against Jackrabbit 2 before reporting an issue against Oak.
-
-Reporting issues
-================
-
-If you encounter a problem where functionality is missing or Oak does not
behave as expected please
-check whether this is a [known change in
behaviour](https://issues.apache.org/jira/browse/OAK-14) or
-a [known issue](https://issues.apache.org/jira/browse/OAK). If in doubt ask on
the [Oak dev list]
-(http://oak.markmail.org/). Otherwise create a [new
issue](https://issues.apache.org/jira/browse/OAK).
-
-Notable changes
-===============
-
-This section gives a brief overview of the most notable changes in Oak with
respect to Jackrabbit 2.
-These changes are generally caused by overall design decisions carefully
considering the benefits
-versus the potential backward compatibility issues.
-
-Session state and refresh behaviour
------------------------------------
-
-In Jackrabbit 2 sessions always reflects the latest state of the repository.
With Oak a session
-reflects a stable view of the repository from the time the session was
acquired ([MVCC model]
-(http://en.wikipedia.org/wiki/MVCC)). This is a fundamental design aspect for
achieving the
-distributed nature of an Oak repository.
-
-This change can cause subtle differences in behavior when two sessions perform
modifications
-relying on one session seeing the other session's changes. Oak requires
explicit calls to
-`Session.refresh()`in this case.
-
-> *Note*: To ease migration to Oak, sessions being idle for more than one
minute will log a warning
-> to the log file. Furthermore sessions are automatically synchronised to
reflect the same state
-> across accesses within a single thread. That is, an older session will see
the changes done
-> through a newer session given both sessions are accessed from within the
same thread.
->
-> Automatic session synchronisation is a transient feature and will most
probably be removed in
-> future versions of Oak. See
[OAK-803](https://issues.apache.org/jira/browse/OAK-803) for further
-> details regarding session backwards compatibility and
-> [OAK-960](https://issues.apache.org/jira/browse/OAK-960) regarding in thread
session
-> synchronisation.
-
-On Oak `Item.refresh()` is deprecated and will always cause an
`Session.refresh()`. The former call
-will result in a warning written to the log in order to facilitate locating
trouble spots.
-
-On Oak `Item.save()` is deprecated and will per default log a warning and fall
back to
-`Session.save()`. This behaviour can be tweaked with
`-Ditem-save-does-session-save=false` in which
-case no fall back to `Session#save()` will happen but an
`UnsupportedRepositoryException` is thrown
-if the sub-tree rooted at the respective item does not contain all transient
changes. See
-[OAK-993](https://issues.apache.org/jira/browse/OAK-993) for details.
-
-Query
------
-
-Oak does not index content by default as does Jackrabbit 2. You need to create
custom indexes when
-necessary, much like in traditional RDBMSs. If there is no index for a
specific query then the
-repository will be traversed. That is, the query will still work but probably
be very slow.
-
-See the [query overview page](query.html) for how to create a custom index.
-
-Observation
------------
-
-Regarding observation listeners:
-
-* `Event.getUserId()`, `Event.getUserData()`and `Event.getDate()` will only be
available for locally
- generated events (i.e. on the same cluster node). To help identifying
potential trouble spots,
- calling any of these methods without a previous call to
`JackrabbitEvent#isExternal()` will write
- a warning to the log file.
-
-* Push notification mechanisms like JCR observation weight heavy on
distributed systems. Therefore,
- if an application requirement is not actually an "eventing problem" consider
using different means
- like query and custom indexes.
- [Apache Sling](http://sling.apache.org) identified and classified common
[usage patterns]
-
(https://cwiki.apache.org/confluence/display/SLING/Observation+usage+patterns)
of observation and
- recommendations on alternative solutions where applicable.
-
-* Touched properties: Jackrabbit 2 used to generate a `PROPERTY_CHANGED` event
when touching a
- property (i.e. setting a property to its current value). Oak keeps closer to
the specification and
- [omits such events](https://issues.apache.org/jira/browse/OAK-948).
-
-* `Event.NODE_MOVED` is not supported. Instead `Event.NODE_ADDED` and
`Event.Node_REMOVED` events are
- reported as long as they don't cancel each other (e.g. in case of reordering
of nodes).
-
-Same name siblings
-------------------
-
-Same name siblings (SNS) are deprecated in Oak. We figured that the actual
benefit supporting same
-name siblings as mandated by JCR is dwarfed by the additional implementation
complexity. Instead
-there are ideas to implement a feature for automatic [disambiguation of node
names](https://issues.apache.org/jira/browse/OAK-129).
-
-In the meanwhile we have [basic
support](https://issues.apache.org/jira/browse/OAK-203) for same
-name siblings but that might not cover all cases.
-
-Authentication
---------------
-
-Please refer to [OAK-793](https://issues.apache.org/jira/browse/OAK-793) for a
general overview of
-changes with respect to Jackrabbit 2.
-
-Access Control Management
--------------------------
-
-Refer to [OAK-792](https://issues.apache.org/jira/browse/OAK-792) for a
general overview of changes
-with respect to Jackrabbit 2.
-
-The following modification are most likely to have an effect on existing
applications:
-
-* `AccessControlManager#hasPrivilege()` and
`AccessControlManager#getPrivileges()` will throw a
- `PathNotFoundException` if the node for the specified path is not
accessible. The Jackrabbit 2
- implementation is wrong and we fixed that in OAK
([OAK-886](https://issues.apache.org/jira/browse/OAK-886)).
- If the new behaviour turns out to be a problem with existing applications we
might consider
- adding backward compatible behaviour.
-
-Permissions
------------
-
-Refer to [OAK-942](https://issues.apache.org/jira/browse/OAK-942) for a
general overview of changes
-with respect to Jackrabbit 2.
-
-* As of Oak `Node#remove()` only requires sufficient permissions to remove the
target node. In
- contrast to jackrabbit the validation will not traverse the tree and verify
remove permission on
- all child nodes/properties. There exists a configuration flag that aims to
produce best effort
- backwards compatibility but this flag is currently not enabled by default.
Please let us know if
- you suspect this causes wrong behavior in your application.
-
-* By default user management operations require the specific user mgt related
- permission that has been introduced with OAK-1.0. This behavior can be
- turned off by setting the corresponding configuration flag.
-
-* As of OAK reading and writing items in the version store does not follow the
- regular permission evaluation but depends on access rights present on the
- corresponding versionable node
[OAK-444](https://issues.apache.org/jira/browse/OAK-444).
-
-Privilege Management
---------------------
-
-Refer to [OAK-910](https://issues.apache.org/jira/browse/OAK-910) for a
general overview of changes
-with respect to Jackrabbit 2.
-
-User Management
----------------
-
-Refer to [OAK-791](https://issues.apache.org/jira/browse/OAK-791) for a
general overview of changes
-with respect to Jackrabbit 2.
-
-Principal Management
---------------------
-
-Refer to [OAK-909](https://issues.apache.org/jira/browse/OAK-909) for a
general overview of changes
-with respect to Jackrabbit 2.
-
Known issues
============
All known issues are listed in the Apache
[JIRA](https://issues.apache.org/jira/browse/OAK).
Modified: jackrabbit/oak/trunk/oak-doc/src/site/site.xml
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/site.xml?rev=1535349&r1=1535348&r2=1535349&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/site.xml (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/site.xml Thu Oct 24 12:25:29 2013
@@ -40,6 +40,7 @@ under the License.
<menu name="Using Oak">
<item href="use_getting_started.html" name="Getting Started" />
<item href="differences.html" name="Differences to Jackrabbit 2" />
+ <item href="known_issues.html" name="Known Issues" />
<item href="dos_and_donts.html" name="Dos and don'ts" />
<item href="when_things_go_wrong.html" name="When things go wrong" />
</menu>
