NavigationManager


1   /*
2    * Copyright 2004 Outerthought bvba and Schaubroeck nv
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.outerj.daisy.navigation;
17  
18  import org.xml.sax.ContentHandler  ;
19  import org.xml.sax.SAXException  ;
20  import org.outerj.daisy.repository.RepositoryException;
21  import org.outerj.daisy.repository.VariantKey;
22  
23  public interface NavigationManager {
24      /**
25       * Generates a navigation tree as XML.
26       *
27       * <p>If the document specified in the NavigationParams as 'activeDocument' cannot be found,
28       * a 'closed' tree will be produced (i.e. a tree generated to node depth level 1) if contextualized is true.
29       * If contextualized is false, a full tree will be genereated.
30       *
31       * <p>The same holds if the the 'activeDocument', or one of the nodes on the path leading to
32       * that document, is not readable by the current user and role.
33       *
34       * @param contentHandler resulting XML will be pushed on this ContentHandler
35       * @param activeDocument the document that should be marked as 'selected' (null for none)
36       * @param handleErrors if true, the navigation tree generation output will first be buffered so that
37       *                     in case an error occurs, some information about this error can be streamed
38       *                     instead of the normal navigation tree outpus
39       * @throws NavigationException in case some error occurs
40       * @throws SAXException never thrown by us, but unavoidable when pushing things to a ContentHandler.
41       */
42      public void generateNavigationTree(ContentHandler   contentHandler, NavigationParams navigationParams,
43              VariantKey activeDocument, boolean handleErrors)
44              throws RepositoryException, SAXException  ;
45  
46      /**
47       * Generates a navigation tree based on the XML given in the navigationTreeXml parameter.
48       * This allows to generate navigation trees from an XML description not stored in the repository.
49       *
50       * <p>The branch and language parameters should be the branch and language that are or will be used
51       * on the site where this navigation tree is published (and thus the branch and language under which
52       * the navigation tree would normally be stored in the repository). They are used as default branch and language
53       * there where one is needed (eg. document and import nodes).
54       */
55      public void generatePreviewNavigationTree(ContentHandler   contentHandler, String   navigationTreeXml,
56              long branchId, long languageId) throws RepositoryException, SAXException  ;
57  
58      /**
59       * Resolves a path (of the form id/id/...) against a (series of) navigation tree(s),
60       * giving a certain result. See {@link NavigationLookupResult}.
61       *
62       * <p>This method is best understood with the structure of the Daisy Wiki, where each 'site'
63       * is associated with a collection and a navigation tree, and the branch and language of the
64       * navigation tree document correspond to the 'default' branch and language for that site.
65       *
66       * <p>The algortihm followed is described below.
67       *
68       * <p>Is the navigationPath found in the navigation tree of the first lookup alternative?
69       *
70       * <ul>
71       *
72       * <li>1. If yes, what is the type of node it addresses?
73       *
74       * <ul>
75       * <li>1-a. If it is a group node, set the result to a redirect to the first (depth-first) document child
76       * descendant of the group node. If the group node does not have any such children, set the result to 'path not found'.
77       *
78       * <li>1-b. If it is a document node, check if the branch and language of the navtree node match the
79       * requested branch and language (if not -1)
80       *
81       * <ul>
82       *  <li>1-b-i.  If they match, set the result to 'match'.
83       *  <li>1-b-ii. If no, search among the lookup alternatives.
84       * </ul>
85       * </ul>
86       *
87       * <li>2. If no, then does the path end on a numeric ID?
88       *
89       * <ul>
90       *  <li>2-a. If no, set the result to 'path not found'.
91       *  <li>2-b. If yes, follow the following algorithm:
92       *  <ul>
93       *   <li>Determine the branch and language (is either the requested branch and language, or those of the navtree
94       *       of the first lookup alternative)
95       *   <li>Retrieve the collections the document belongs to. If this fails for whathever reason (usually permissions
96       *       or existence), just set the result to 'match'. When the front end will then try
97       *       to display the document, it will run into this error and show it to the user.
98       *   <li>Run over the lookup alternatives:
99       *  <ul>
100      *  <li>If the collection, navtree-branch and navtree-language of a lookup alternative match those of the document:
101      *  <ul>
102      *   <li>If this is the first match, remember it as "firstMatch"
103      *   <li>If found in the navtree of this lookup alternative, set the result to a redirect to this lookup alternative
104      *       and navigation path. Done.
105      *  </ul>
106      *  <li>If we ran over all the lookup alternatives and none matched:
107      *  <ul>
108      *   <li>If 'firstMatch' is set and is different from first lookup alternative, set result to redirect to the lookup alternative
109      *   <li>Otherwise set result to 'match' (as if it was found at whatever location that was requested).
110      *  </ul>
111      * </ul>
112      * </ul>
113      *
114      * @param requestedBranchId if the branch of the document differs the one in the navtree node, this argument
115      *               specifies the branch ID, otherwise supply -1.
116      * @param requestedLanguageId dito as for requestedBranchId
117      * @param lookupAlternatives should at least contain one entry
118      */
119     public NavigationLookupResult lookup(String   navigationPath, long requestedBranchId, long requestedLanguageId,
120             LookupAlternative[] lookupAlternatives) throws RepositoryException;
121 
122     /**
123      * Searches a  possible path in the navigation tree for the given document, or null if none
124      * exists.
125      */
126     public String   reverseLookup(VariantKey document, VariantKey navigationDoc, NavigationVersionMode versionMode) throws RepositoryException;
127 
128     /**
129      * Same as the other reverseLookup method, but defaults to the live version mode.
130      */
131     public String   reverseLookup(VariantKey document, VariantKey navigationDoc) throws RepositoryException;
132 }
133
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags