[Navigation] Prevent navigation to orphan objects

This is particularly useful when a persistence failure has caused
a created object not to be added to its parent container. #765

platform/commonUI/browse/src/navigation/OrphanNavigationHandler.js

@@ -0,0 +1,75 @@
+/*****************************************************************************
+ * Open MCT Web, Copyright (c) 2014-2015, United States Government
+ * as represented by the Administrator of the National Aeronautics and Space
+ * Administration. All rights reserved.
+ *
+ * Open MCT Web is licensed 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.
+ *
+ * Open MCT Web includes source code licensed under additional open source
+ * licenses. See the Open Source Licenses file (LICENSES.md) included with
+ * this source code distribution or the Licensing information page available
+ * at runtime from the About dialog for additional information.
+ *****************************************************************************/
+
+define([], function () {
+
+    /**
+     * Navigates away from orphan objects whenever they are detected.
+     *
+     * An orphan object is an object whose apparent parent does not
+     * actually contain it. This may occur in certain circumstances, such
+     * as when persistence succeeds for a newly-created object but fails
+     * for its parent.
+     *
+     * @param throttle the `throttle` service
+     * @param topic the `topic` service
+     * @param navigationService the `navigationService`
+     * @constructor
+     */
+    function OrphanNavigationHandler(throttle, topic, navigationService) {
+        var throttledCheckNavigation;
+
+        function getParent(domainObject) {
+            var context = domainObject.getCapability('context');
+            return context.getParent();
+        }
+
+        function isOrphan(domainObject) {
+            var parent = getParent(domainObject),
+                composition = parent.getModel().composition,
+                id = domainObject.getId();
+            return !composition || (composition.indexOf(id) === -1);
+        }
+
+        function navigateToParent(domainObject) {
+            var parent = getParent(domainObject);
+            return parent.getCapability('action').perform('navigate');
+        }
+
+        function checkNavigation() {
+            var navigatedObject = navigationService.getNavigation();
+            if (navigatedObject.hasCapability('context') &&
+                isOrphan(navigatedObject)) {
+                if (!navigatedObject.getCapability('editor').isEditContextRoot()) {
+                    navigateToParent(navigatedObject);
+                }
+            }
+        }
+
+        throttledCheckNavigation = throttle(checkNavigation);
+
+        navigationService.addListener(throttledCheckNavigation);
+        topic('mutation').listen(throttledCheckNavigation);
+    }
+
+    return OrphanNavigationHandler;
+});