MVCGroup.java
001 /*
002  * SPDX-License-Identifier: Apache-2.0
003  *
004  * Copyright 2008-2017 the original author or authors.
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 package griffon.core.mvc;
019 
020 import griffon.core.Context;
021 import griffon.core.artifact.GriffonController;
022 import griffon.core.artifact.GriffonModel;
023 import griffon.core.artifact.GriffonView;
024 
025 import javax.annotation.Nonnull;
026 import javax.annotation.Nullable;
027 import java.util.Map;
028 
029 /**
030  * Defines an MVC group and its contents
031  *
032  @author Andres Almiray
033  @since 2.0.0
034  */
035 public interface MVCGroup extends MVCHandler {
036     /**
037      * Returns the configuration of this group.
038      *
039      @return the configuration used to instantiate this group.
040      */
041     @Nonnull
042     MVCGroupConfiguration getConfiguration();
043 
044     /**
045      * Returns the type of this group as set in the application's configuration.
046      *
047      @return the type of the group
048      */
049     @Nonnull
050     String getMvcType();
051 
052     /**
053      * Returns the id of the group.
054      * Ids are used to uniquely identify a group instance.
055      *
056      @return the id of this group.
057      */
058     @Nonnull
059     String getMvcId();
060 
061     /**
062      * Returns the Model portion of this group.
063      *
064      @return a GriffonModel instance if the group has a model member, null otherwise
065      @throws IllegalStateException if the group has been destroyed already
066      */
067     @Nullable
068     GriffonModel getModel();
069 
070     /**
071      * Returns the View portion of this group.
072      *
073      @return a GriffonView instance if the group has a view member, null otherwise
074      @throws IllegalStateException if the group has been destroyed already
075      */
076     @Nullable
077     GriffonView getView();
078 
079     /**
080      * Returns the Controller portion of this group.
081      *
082      @return a GriffonController instance if the group has a controller member, null otherwise
083      @throws IllegalStateException if the group has been destroyed already
084      */
085     @Nullable
086     GriffonController getController();
087 
088     /**
089      * Returns the specified member type.
090      *
091      @param name the type of member to retrieve
092      @return the selected MVC member if a match is found, null otherwise
093      @throws IllegalStateException if the group has been destroyed already
094      */
095     @Nullable
096     Object getMember(@Nonnull String name);
097 
098     /**
099      * Returns a read-only view of all instance members.
100      *
101      @return an unmodifiable Map view of all members.
102      @throws IllegalStateException if the group has been destroyed already
103      */
104     @Nonnull
105     Map<String, Object> getMembers();
106 
107     /**
108      * Destroys the current group.
109      <strong>Should only be called once.</strong>
110      *
111      @throws IllegalStateException if the group has been destroyed already
112      */
113     void destroy();
114 
115     /**
116      * Returns whether this group has been destroyed or not.
117      *
118      @return true if the group has not been destroyed yet, false otherwise
119      */
120     boolean isAlive();
121 
122     /**
123      * Returns the context belonging to this group.
124      *
125      @since 2.2.0
126      */
127     @Nonnull
128     Context getContext();
129 
130     /**
131      * Returns the parent {@code MVCGroup} of this group.
132      <p>The parent may be null if this is a top level MVC group.</p>
133      *
134      @since 2.2.0
135      */
136     @Nullable
137     MVCGroup getParentGroup();
138 
139     /**
140      * Returns an immutable view of all children groups for which this group is a parent
141      *
142      @return an immutable view of children groups, keyed by mvcId.
143      @since 2.4.0
144      */
145     @Nonnull
146     Map<String, MVCGroup> getChildrenGroups();
147 
148     /**
149      * Notifies the group when another MVC group has been destroyed, potentially
150      * a child group.
151      *
152      @param mvcId the id of the group that has been destroyed
153      @since 2.4.0
154      */
155     void notifyMVCGroupDestroyed(@Nonnull String mvcId);
156 }