001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  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,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.api.core;
020
021import java.util.Date;
022import java.util.Map;
023
024
025public interface Page extends Cloneable, Comparable< Page > {
026
027    /** "Summary" is a short summary of the page.  It is a String. */
028    String DESCRIPTION = "summary";
029
030    /** A special variable name for storing a page alias. */
031    String ALIAS = "alias";
032
033    /** A special variable name for storing a redirect note */
034    String REDIRECT = "redirect";
035
036    /** A special variable name for storing the author. */
037    String AUTHOR = "author";
038
039    /** A special variable name for storing a changenote. */
040    String CHANGENOTE = "changenote";
041
042    /** A special variable name for storing a viewcount. */
043    String VIEWCOUNT = "viewcount";
044
045    /**
046     *  Returns the name of the page.
047     *
048     *  @return The page name.
049     */
050    String getName();
051
052    /**
053     *  Returns the date when this page was last modified.
054     *
055     *  @return The last modification date
056     */
057    Date getLastModified();
058
059    /**
060     *  Sets the last modification date.  In general, this is only changed by the provider.
061     *
062     *  @param date The date
063     */
064    void setLastModified( Date date );
065
066    /**
067     *  Sets the page version.  In general, this is only changed by the provider.
068     *
069     *  @param version The version number
070     */
071    void setVersion( int version );
072
073    /**
074     *  Returns the version that this WikiPage instance represents.
075     *
076     *  @return the version number of this page.
077     */
078    int getVersion();
079
080    /**
081     *  Returns the size of the page.
082     *
083     *  @return the size of the page. 
084     *  @since 2.1.109
085     */
086    long getSize();
087
088    /**
089     *  Sets the size.  Typically called by the provider only.
090     *
091     *  @param size The size of the page.
092     *  @since 2.1.109
093     */
094    void setSize( long size );
095
096    /**
097     *  Sets the author of the page.  Typically called only by the provider.
098     *
099     *  @param author The author name.
100     */
101    void setAuthor( String author );
102
103    /**
104     *  Returns author name, or null, if no author has been defined.
105     *
106     *  @return Author name, or possibly null.
107     */
108    String getAuthor();
109
110    /**
111     *  Returns the wiki name for this page
112     *
113     *  @return The name of the wiki.
114     */
115    String getWiki();
116
117    /** This method will remove all metadata from the page. */
118    void invalidateMetadata();
119
120    /**
121     *  Returns <code>true</code> if the page has valid metadata; that is, it has been parsed. Note that this method is a kludge to
122     *  support our pre-3.0 metadata system, and as such will go away with the new API.
123     *
124     *  @return true, if the page has metadata.
125     */
126    boolean hasMetadata();
127
128    /** Sets the metadata flag to true.  Never call. */
129    void setHasMetadata();
130
131    /**
132     *  A WikiPage may have a number of attributes, which might or might not be  available.  Typically attributes are things that do not
133     *  need to be stored with the wiki page to the page repository, but are generated on-the-fly.  A provider is not required to save 
134     *  them, but they can do that if they really want.
135     *
136     *  @param key The key using which the attribute is fetched
137     *  @return The attribute.  If the attribute has not been set, returns null.
138     */
139    < T > T getAttribute( String key );
140
141    /**
142     *  Sets an metadata attribute.
143     *
144     *  @see #getAttribute(String)
145     *  @param key The key for the attribute used to fetch the attribute later on.
146     *  @param attribute The attribute value
147     */
148    void setAttribute( String key, Object attribute );
149
150    /**
151     *  Removes an attribute from the page, if it exists.
152     *
153     *  @param  key The key for the attribute
154     *  @return If the attribute existed, returns the object.
155     *  @since 2.1.111
156     */
157    < T > T removeAttribute( String key );
158
159    /**
160     * Returns the full attributes Map, in case external code needs to iterate through the attributes.
161     *
162     * @return The attribute Map.  Please note that this is a direct reference, not a copy.
163     */
164    Map< String, Object > getAttributes();
165
166    /**
167     *  Returns the Acl for this page.  May return <code>null</code>, in case there is no Acl defined, or it has not
168     *  yet been set by {@link #setAcl(Acl)}.
169     *
170     *  @return The access control list.  May return null, if there is  no acl.
171     */
172    Acl getAcl();
173
174    /**
175     * Sets the Acl for this page. Note that method does <em>not</em> persist the Acl itself to back-end storage or in page markup;
176     * it merely sets the internal field that stores the Acl. To persist the Acl, callers should invoke 
177     * {@link org.apache.wiki.auth.acl.AclManager#setPermissions(org.apache.wiki.api.core.Page, org.apache.wiki.api.core.Acl)}.
178     *
179     * @param acl The Acl to set
180     */
181    void setAcl( Acl acl );
182
183    /** {@inheritDoc} */
184    Page clone();
185
186}