001: /*
002: * Copyright 2004 Outerthought bvba and Schaubroeck nv
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.outerj.daisy.navigation;
017:
018: import org.xml.sax.ContentHandler;
019: import org.xml.sax.SAXException;
020: import org.outerj.daisy.repository.RepositoryException;
021: import org.outerj.daisy.repository.VariantKey;
022:
023: import java.util.Locale;
024:
025: /**
026: * The NavigationManager generates hierarchical navigation trees from an XML
027: * navigation tree specification. The navigation tree specification is read from
028: * a Daisy repository document (from the content of the "NavigationData" part) and
029: * can contain a literal enumeration of documents but also queries.
030: *
031: * <p>The navigation trees support quite some features, we refer to the Daisy documentation
032: * for more information on this.
033: *
034: * <p>This is an optional repository extension component.
035: *
036: * <p>The NavigationManager is obtained from the {@link org.outerj.daisy.repository.Repository Repository} as
037: * follows:
038: *
039: * <pre>
040: * NavigationManager navManager = (NavigationManager)repository.getExtension("NavigationManager");
041: * </pre>
042: *
043: * <p>In the remote repository API, the NavigationManager extension can be registered as follows:
044: *
045: * <pre>
046: * RemoteRepositoryManager repositoryManager = ...;
047: * repositoryManager.registerExtension("NavigationManager",
048: * new Packages.org.outerj.daisy.navigation.clientimpl.RemoteNavigationManagerProvider());
049: * </pre>
050: */
051: public interface NavigationManager {
052: /**
053: * Generates a navigation tree as XML.
054: *
055: * <p>If the document specified in the NavigationParams as 'activeDocument' cannot be found,
056: * a 'closed' tree will be produced (i.e. a tree generated to node depth level 1) if contextualized is true.
057: * If contextualized is false, a full tree will be genereated.
058: *
059: * <p>The same holds if the the 'activeDocument', or one of the nodes on the path leading to
060: * that document, is not readable by the current user and role.
061: *
062: * @param contentHandler resulting XML will be pushed on this ContentHandler
063: * @param activeDocument the document that should be marked as 'selected' (null for none)
064: * @param handleErrors if true, the navigation tree generation output will first be buffered so that
065: * in case an error occurs, some information about this error can be streamed
066: * instead of the normal navigation tree outpus
067: * @throws NavigationException in case some error occurs
068: * @throws SAXException never thrown by us, but unavoidable when pushing things to a ContentHandler.
069: */
070: public void generateNavigationTree(ContentHandler contentHandler,
071: NavigationParams navigationParams,
072: VariantKey activeDocument, boolean handleErrors)
073: throws RepositoryException, SAXException;
074:
075: /**
076: * Generates a navigation tree based on the XML given in the navigationTreeXml parameter.
077: * This allows to generate navigation trees from an XML description not stored in the repository.
078: *
079: * <p>The branch and language parameters should be the branch and language that are or will be used
080: * on the site where this navigation tree is published (and thus the branch and language under which
081: * the navigation tree would normally be stored in the repository). They are used as default branch and language
082: * there where one is needed (eg. document and import nodes).
083: */
084: public void generatePreviewNavigationTree(
085: ContentHandler contentHandler, String navigationTreeXml,
086: long branchId, long languageId, Locale locale)
087: throws RepositoryException, SAXException;
088:
089: /**
090: * Same as the other generatePreviewNavigationTree method, but without Locale parameter
091: * (defaults to Locale.US), for backwards compatibility.
092: */
093: public void generatePreviewNavigationTree(
094: ContentHandler contentHandler, String navigationTreeXml,
095: long branchId, long languageId) throws RepositoryException,
096: SAXException;
097:
098: /**
099: * Resolves a path (of the form id/id/...) against a (series of) navigation tree(s),
100: * giving a certain result. See {@link NavigationLookupResult}.
101: *
102: * <p>This method is best understood with the structure of the Daisy Wiki, where each 'site'
103: * is associated with a collection and a navigation tree, and the branch and language of the
104: * navigation tree document correspond to the 'default' branch and language for that site.
105: *
106: * <p>The algortihm followed is described below.
107: *
108: * <p>Is the navigationPath found in the navigation tree of the first lookup alternative?
109: *
110: * <ul>
111: *
112: * <li>1. If yes, what is the type of node it addresses?
113: *
114: * <ul>
115: * <li>1-a. If it is a group node, set the result to a redirect to the first (depth-first) document child
116: * descendant of the group node. If the group node does not have any such children, set the result to 'path not found'.
117: *
118: * <li>1-b. If it is a document node, check if the branch and language of the navtree node match the
119: * requested branch and language (if not -1)
120: *
121: * <ul>
122: * <li>1-b-i. If they match, set the result to 'match'.
123: * <li>1-b-ii. If no, search among the lookup alternatives.
124: * </ul>
125: * </ul>
126: *
127: * <li>2. If no, then does the path end on a numeric ID?
128: *
129: * <ul>
130: * <li>2-a. If no, set the result to 'path not found'.
131: * <li>2-b. If yes, follow the following algorithm:
132: * <ul>
133: * <li>Determine the branch and language (is either the requested branch and language, or those of the navtree
134: * of the first lookup alternative)
135: * <li>Retrieve the collections the document belongs to. If this fails for whathever reason (usually permissions
136: * or existence), just set the result to 'match'. When the front end will then try
137: * to display the document, it will run into this error and show it to the user.
138: * <li>Run over the lookup alternatives:
139: * <ul>
140: * <li>If the collection, navtree-branch and navtree-language of a lookup alternative match those of the document:
141: * <ul>
142: * <li>If this is the first match, remember it as "firstMatch"
143: * <li>If found in the navtree of this lookup alternative, set the result to a redirect to this lookup alternative
144: * and navigation path. Done.
145: * </ul>
146: * <li>If we ran over all the lookup alternatives and none matched:
147: * <ul>
148: * <li>If 'firstMatch' is set and is different from first lookup alternative, set result to redirect to the lookup alternative
149: * <li>Otherwise set result to 'match' (as if it was found at whatever location that was requested).
150: * </ul>
151: * </ul>
152: * </ul>
153: *
154: * @param requestedBranchId if the branch of the document differs the one in the navtree node, this argument
155: * specifies the branch ID, otherwise supply -1.
156: * @param requestedLanguageId dito as for requestedBranchId
157: * @param lookupAlternatives should at least contain one entry
158: */
159: public NavigationLookupResult lookup(String navigationPath,
160: long requestedBranchId, long requestedLanguageId,
161: LookupAlternative[] lookupAlternatives)
162: throws RepositoryException;
163:
164: /**
165: * Searches a possible path in the navigation tree for the given document, or null if none
166: * exists.
167: */
168: public String reverseLookup(VariantKey document,
169: VariantKey navigationDoc, NavigationVersionMode versionMode)
170: throws RepositoryException;
171:
172: /**
173: * Same as the other reverseLookup method, but defaults to the live version mode.
174: */
175: public String reverseLookup(VariantKey document,
176: VariantKey navigationDoc) throws RepositoryException;
177: }
|