    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}