Package: Layout

Layout

Coverage

1: /*
2: * *************************************************************************************************************************************************************
3: *
4: * NorthernWind - lightweight CMS
5: * http://tidalwave.it/projects/northernwind
6: *
7: * Copyright (C) 2011 - 2025 Tidalwave s.a.s. (http://tidalwave.it)
8: *
9: * *************************************************************************************************************************************************************
10: *
11: * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
12: * You may obtain a copy of the License at
13: *
14: * http://www.apache.org/licenses/LICENSE-2.0
15: *
16: * 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
17: * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
18: *
19: * *************************************************************************************************************************************************************
20: *
21: * git clone https://bitbucket.org/tidalwave/northernwind-src
22: * git clone https://github.com/tidalwave-it/northernwind-src
23: *
24: * *************************************************************************************************************************************************************
25: */
26: package it.tidalwave.northernwind.frontend.ui;
27:
28: import javax.annotation.Nonnull;
29: import java.util.Optional;
30: import it.tidalwave.util.As;
31: import it.tidalwave.util.Id;
32: import it.tidalwave.util.NotFoundException;
33: import it.tidalwave.role.Composite;
34: import it.tidalwave.role.Identifiable;
35: import it.tidalwave.northernwind.core.model.HttpStatusException;
36: import it.tidalwave.northernwind.core.model.ModelFactory;
37: import it.tidalwave.northernwind.core.model.SiteNode;
38: import it.tidalwave.northernwind.frontend.ui.ViewFactory.ViewAndController;
39: import lombok.AccessLevel;
40: import lombok.AllArgsConstructor;
41: import lombok.Getter;
42: import lombok.RequiredArgsConstructor;
43: import lombok.ToString;
44: import lombok.With;
45:
46: /***************************************************************************************************************************************************************
47: *
48: * A {@code Layout} contains the description of the visual structure of a {@link SiteNode}.
49: *
50: * @author Fabrizio Giudici
51: *
52: **************************************************************************************************************************************************************/
53: public interface Layout extends As, Identifiable, Composite<Layout, LayoutFinder>
54: {
55: /***********************************************************************************************************************************************************
56: * A builder of a {@link Layout}.
57: **********************************************************************************************************************************************************/
58: @AllArgsConstructor(access = AccessLevel.PRIVATE) @RequiredArgsConstructor
59: @Getter @ToString(exclude = "callBack")
60: public final class Builder
61: {
62: // Workaround for a Lombok limitation with Wither and subclasses
63: @FunctionalInterface
64: public static interface CallBack
65: {
66: @Nonnull
67: public Layout build (@Nonnull Builder builder);
68: }
69:
70: @Nonnull
71: private final ModelFactory modelFactory;
72:
73: @Nonnull
74: private final CallBack callBack;
75:
76: @With
77: private Id id;
78:
79: @With
80: private String type;
81:
82: @Nonnull
83: public Layout build()
84: {
85: return callBack.build(this);
86: }
87: }
88:
89: /***********************************************************************************************************************************************************
90: * Returns the type URI for this layout.
91: *
92: * @return the type URI
93: **********************************************************************************************************************************************************/
94: @Nonnull
95: public String getTypeUri(); // FIXME: perhaps String should be a LayoutType wrapper? Or an Id?
96:
97: /***********************************************************************************************************************************************************
98: * Creates a clone with another {@code Layout} as a child.
99: *
100: * @param child the child {@code Layout}
101: * @return the clone with the new child
102: **********************************************************************************************************************************************************/
103: @Nonnull
104: public Layout withChild (@Nonnull Layout child);
105:
106: /***********************************************************************************************************************************************************
107: * Creates a clone with another {@code Layout} overriding some parts.
108: *
109: * @param override the overriding {@code Layout}
110: * @return the clone with the override in effect
111: **********************************************************************************************************************************************************/
112: @Nonnull
113: public Layout withOverride (@Nonnull Layout override);
114:
115: /***********************************************************************************************************************************************************
116: * Accepts a {@link Visitor} to walk inside the structure and returns the (optional) computation product of the
117: * {@code Visitor}.
118: *
119: * @param visitor the {@code Visitor}
120: * @return the {@code Visitor} result
121: **********************************************************************************************************************************************************/
122: @Nonnull // TODO: push up to Composite
123: public <T> Optional<T> accept (@Nonnull Visitor<? super Layout, T> visitor);
124:
125: /***********************************************************************************************************************************************************
126: * Creates a new {@link View} with its {@link Controller} for the given {@link SiteNode}, typically because
127: * something needs to render it in response of a request.
128: *
129: * @param siteNode the {@code SiteNode}
130: * @return the {@code View} and its {@code Controller} within a {@link ViewAndController}
131: * @throws NotFoundException if no view component is found
132: * @throws HttpStatusException if a component asked to return a specific HTTP status
133: **********************************************************************************************************************************************************/
134: @Nonnull
135: public ViewAndController createViewAndController (@Nonnull SiteNode siteNode)
136: throws NotFoundException, HttpStatusException;
137: }