1 /*
2 * Copyright 2016 Function1. All Rights Reserved.
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 tools.gsf.navigation;
17
18 import java.util.List;
19
20 /**
21 * Service that exposes hierarchical navigation structures in the form of <code>Node</code>s.
22 *
23 * The service also allows an object present in or related to the navigation structures to access its breadcrumb.
24 * An object's breadcrumb is defined as the <em>preferred</em> path through the navigation structures from the
25 * root of the entire site to the specified object.
26 *
27 * In specifying "preferred" it therefore follows that an object that is present or related to more than one location
28 * in the navigation structures (and can therefore be reached by traversing the navs in more than one way) may only
29 * have one single breadcrumb path.
30 *
31 * @author Tony Field
32 * @since 2016-06-28
33 */
34 public interface NavService<N extends Node<N>, S, P> {
35
36 /**
37 * Returns the nodes corresponding to the nav structure specified.
38 *
39 * @param id an identifier that specifies which nav structure should be loaded.
40 * @return a list of the nodes at the root of the nav structure specified. Never null.
41 * @throws IllegalArgumentException if the structure specified is invalid.
42 */
43 List<N> getNav(S id);
44
45 /**
46 * Return the preferred breadcrumb path from the root of the site to the object specified.
47 *
48 * An object's breadcrumb is defined as the <em>preferred</em> path through the navigation structures from the
49 * root of the entire site to the specified object.
50 *
51 * In specifying "preferred" it therefore follows that an object that is present or related to more than one location
52 * in the navigation structures (and can therefore be reached by traversing the navs in more than one way) may only
53 * have one single breadcrumb path.
54 *
55 * @param obj object participating in the navigation structure
56 * @return list of nodes, starting with the root node of the site and ending with the node corresponding to
57 * the specified object.
58 * @throws IllegalArgumentException if the specified object is not present or related to an object in the nav
59 * structures of this site.
60 */
61 List<N> getBreadcrumb(P obj);
62
63 }