/* 
    P/P   *  Method: org.apache.roller.weblogger.business.UserManager__static_init
          */
     1  /*
     2   * Licensed to the Apache Software Foundation (ASF) under one or more
     3   *  contributor license agreements.  The ASF licenses this file to You
     4   * under the Apache License, Version 2.0 (the "License"); you may not
     5   * 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.  For additional information regarding
    15   * copyright in this work, please see the NOTICE file in the top level
    16   * directory of this distribution.
    17   */
    18  
    19  package org.apache.roller.weblogger.business;
    20  
    21  import java.util.Date;
    22  import java.util.List;
    23  import java.util.Map;
    24  import org.apache.roller.weblogger.WebloggerException;
    25  import org.apache.roller.weblogger.pojos.WeblogTemplate;
    26  import org.apache.roller.weblogger.pojos.WeblogPermission;
    27  import org.apache.roller.weblogger.pojos.User;
    28  import org.apache.roller.weblogger.pojos.Weblog;
    29  
    30  
    31  /**
    32   * Manages users, weblogs, permissions, and weblog pages.
    33   */
    34  public interface UserManager {
    35      
    36      /**
    37       * Add a new user.
    38       * 
    39       * This method is used to provide supplemental data to new user accounts,
    40       * such as adding the proper roles for the user.  This method should see
    41       * if the new user is the first user and give that user the admin role if so.
    42       *
    43       * @param newUser User object to be added.
    44       * @throws WebloggerException If there is a problem.
    45       */
    46      public void addUser(User newUser) throws WebloggerException;
    47      
    48      
    49      /**
    50       * Save a user.
    51       *
    52       * @param user User to be saved.
    53       * @throws WebloggerException If there is a problem.
    54       */
    55      public void saveUser(User user) throws WebloggerException;
    56      
    57      
    58      /**
    59       * Remove a user.
    60       *
    61       * @param user User to be removed.
    62       * @throws WebloggerException If there is a problem.
    63       */
    64      public void removeUser(User user) throws WebloggerException;
    65      
    66      
    67      /**
    68       * Lookup a user by ID.
    69       * 
    70       * @param id ID of user to lookup.
    71       * @returns UsUserhe user, or null if not found.
    72       * @throws WebloggerException If there is a problem.
    73       */
    74      public User getUser(String id) throws WebloggerException;
    75      
    76      
    77      /**
    78       * Lookup a user by UserName.
    79       * 
    80       * This lookup is restricted to 'enabled' users by default.  So this method
    81       * should return null if the user is found but is not enabled.
    82       * 
    83       * @param userName User Name of user to lookup.
    84       * @returns UsUserhe user, or null if not found or is disabled.
    85       * @throws WebloggerException If there is a problem.
    86       */
    87      public User getUserByUserName(String userName) throws WebloggerException;
    88      
    89      
    90      /**
    91       * Lookup a user by UserName with the given enabled status.
    92       * 
    93       * @param userName User Name of user to lookup.
    94       * @returns UsUserhe user, or null if not found or doesn't match 
    95       *   the proper enabled status.
    96       * @throws WebloggerException If there is a problem.
    97       */
    98      public User getUserByUserName(String userName, Boolean enabled)
    99          throws WebloggerException;
   100      
   101      
   102      /**
   103       * Lookup a group of users.
   104       * 
   105       * The lookup may be constrained to users with a certain enabled status,
   106       * to users created within a certain date range, and the results can be
   107       * confined to a certain offset & length for paging abilities.
   108       * 
   109       * @param weblog Confine results to users with permission to a certain weblog.
   110       * @param enabled True for enabled only, False for disabled only (or null for all)
   111       * @param startDate Restrict to those created after startDate (or null for all)
   112       * @param endDate Restrict to those created before startDate (or null for all)
   113       * @param offset The index of the first result to return.
   114       * @param length The number of results to return.
   115       * @returns List A list of UserDatUsers which match the criteria.
   116       * @throws WebloggerException If there is a problem.
   117       */
   118      public List getUsers(
   119              Weblog weblog,
   120              Boolean enabled,
   121              Date    startDate,
   122              Date    endDate,
   123              int     offset,
   124              int     length) throws WebloggerException;
   125      
   126      
   127      /**
   128       * Lookup users whose usernames or email addresses start with a string.
   129       *
   130       * @param startsWith String to match userNames and emailAddresses against
   131       * @param offset     Offset into results (for paging)
   132       * @param length     Max to return (for paging)
   133       * @param enabled    True for only enalbed, false for disabled, null for all
   134       * @return List of (up to length) users that match startsWith string
   135       */
   136      public List getUsersStartingWith(String startsWith,
   137              Boolean enabled, int offset, int length) throws WebloggerException;
   138      
   139      
   140      /**
   141       * Get map with 26 entries, one for each letter A-Z and
   142       * containing integers reflecting the number of users whose
   143       * names start with each letter.
   144       */
   145      public Map getUserNameLetterMap() throws WebloggerException;
   146      
   147      
   148      /** 
   149       * Get collection of users whose names begin with specified letter 
   150       */
   151      public List getUsersByLetter(char letter, int offset, int length) 
   152          throws WebloggerException;
   153      
   154      
   155      /**
   156       * Add new website, give creator admin permission, creates blogroll,
   157       * creates categories and other objects required for new website.
   158       * @param newWebsite New website to be created, must have creator.
   159       */
   160      public void addWebsite(Weblog newWebsite) throws WebloggerException;
   161      
   162      
   163      /**
   164       * Store a single weblog.
   165       */
   166      public void saveWebsite(Weblog data) throws WebloggerException;
   167      
   168      
   169      /**
   170       * Remove website object.
   171       */
   172      public void removeWebsite(Weblog website) throws WebloggerException;
   173      
   174      
   175      /**
   176       * Get website object by name.
   177       */
   178      public Weblog getWebsite(String id) throws WebloggerException;
   179      
   180      
   181      /**
   182       * Get website specified by handle (or null if enabled website not found).
   183       * @param handle  Handle of website
   184       */
   185      public Weblog getWebsiteByHandle(String handle) throws WebloggerException;
   186      
   187      
   188      /**
   189       * Get website specified by handle with option to return only enabled websites.
   190       * @param handle  Handle of website
   191       */
   192      public Weblog getWebsiteByHandle(String handle, Boolean enabled)
   193          throws WebloggerException;
   194      
   195      
   196      /**
   197       * Get websites optionally restricted by user, enabled and active status.
   198       * @param user    Get all websites for this user (or null for all)
   199       * @param offset  Offset into results (for paging)
   200       * @param len     Maximum number of results to return (for paging)
   201       * @param enabled Get all with this enabled state (or null or all)
   202       * @param active  Get all with this active state (or null or all)
   203       * @param startDate Restrict to those created after (or null for all)
   204       * @param endDate Restrict to those created before (or null for all)
   205       * @returns List of WebsiteData objects.
   206       */
   207      public List getWebsites(
   208              User user,
   209              Boolean  enabled,
   210              Boolean  active,
   211              Date     startDate,
   212              Date     endDate,
   213              int      offset,
   214              int      length)
   215              throws WebloggerException;
   216      
   217      
   218      /**
   219       * Get websites ordered by descending number of comments.
   220       * @param startDate Restrict to those created after (or null for all)
   221       * @param endDate Restrict to those created before (or null for all)
   222       * @param offset    Offset into results (for paging)
   223       * @param len       Maximum number of results to return (for paging)
   224       * @returns List of WebsiteData objects.
   225       */
   226      public List getMostCommentedWebsites(
   227              Date startDate,
   228              Date endDate,
   229              int  offset,
   230              int  length)
   231              throws WebloggerException;
   232      
   233      
   234      /**
   235       * Get map with 26 entries, one for each letter A-Z and
   236       * containing integers reflecting the number of weblogs whose
   237       * names start with each letter.
   238       */
   239      public Map getWeblogHandleLetterMap() throws WebloggerException;
   240      
   241      
   242      /** 
   243       * Get collection of weblogs whose handles begin with specified letter 
   244       */
   245      public List getWeblogsByLetter(char letter, int offset, int length) 
   246          throws WebloggerException;
   247      
   248      
   249      /**
   250       * Save permissions object.
   251       */
   252      public void savePermissions(WeblogPermission perms) throws WebloggerException;
   253      
   254      
   255      /**
   256       * Remove permissions object.
   257       */
   258      public void removePermissions(WeblogPermission perms) throws WebloggerException;
   259      
   260      
   261      /**
   262       * Get permissions object by id.
   263       */
   264      public WeblogPermission getPermissions(String id) throws WebloggerException;
   265      
   266      
   267      /**
   268       * Get pending permissions for user.
   269       * @param user User (not null)
   270       * @returns List of PermissionsData objects.
   271       */
   272      public List getPendingPermissions(User user) throws WebloggerException;
   273      
   274      
   275      /**
   276       * Get pending permissions for website.
   277       * @param website Website (not null)
   278       * @returns List of PermissionsData objects.
   279       */
   280      public List getPendingPermissions(Weblog user) throws WebloggerException;
   281      
   282      
   283      /**
   284       * Get permissions of user in website.
   285       * @param website Website (not null)
   286       * @param user    User (not null)
   287       * @return        PermissionsData object
   288       */
   289      public WeblogPermission getPermissions(Weblog website, User user)
   290          throws WebloggerException;
   291      
   292      
   293      /**
   294       * Get all permissions in website
   295       * @param website Website (not null)
   296       * @return        PermissionsData object
   297       */
   298      public List getAllPermissions(Weblog website) throws WebloggerException;
   299      
   300      
   301      /**
   302       * Get all permissions of user
   303       * @param user User (not null)
   304       * @return     PermissionsData object
   305       */
   306      public List getAllPermissions(User user) throws WebloggerException;
   307      
   308      
   309      /**
   310       * Invite user to join a website with specific permissions
   311       * @param website Website to be joined (persistent instance)
   312       * @param user    User to be invited (persistent instance)
   313       * @param perms   Permissions mask (see statics in PermissionsData)
   314       * @return        New PermissionsData object, with pending=true
   315       */
   316      public WeblogPermission inviteUser(Weblog website, User user, short perms)
   317          throws WebloggerException;
   318      
   319      
   320      /**
   321       * Retire user from a website
   322       * @param website Website to be retired from (persistent instance)
   323       * @param user    User to be retired (persistent instance)
   324       */
   325      public void retireUser(Weblog website, User user)
   326          throws WebloggerException;
   327      
   328      
   329      /**
   330       * Revoke role of user
   331       * @param roleName Name of the role to be revoked
   332       * @param user    User for whom the role is to be revoked
   333       */
   334      public void revokeRole(String roleName, User user)
   335          throws WebloggerException;
   336  
   337      /**
   338       * Store page.
   339       */
   340      public void savePage(WeblogTemplate data) throws WebloggerException;
   341      
   342      
   343      /**
   344       * Remove page.
   345       */
   346      public void removePage(WeblogTemplate page) throws WebloggerException;
   347      
   348      
   349      /**
   350       * Get page by id.
   351       */
   352      public WeblogTemplate getPage(String id) throws WebloggerException;
   353      
   354      
   355      /**
   356       * Get user's page by action.
   357       */
   358      public WeblogTemplate getPageByAction(Weblog w, String a) throws WebloggerException;
   359      
   360      
   361      /**
   362       * Get user's page by name.
   363       */
   364      public WeblogTemplate getPageByName(Weblog w, String p) throws WebloggerException;
   365      
   366      
   367      /**
   368       * Get website's page by link.
   369       */
   370      public WeblogTemplate getPageByLink(Weblog w, String p)
   371          throws WebloggerException;
   372      
   373      
   374      /**
   375       * Get website's pages
   376       */
   377      public List getPages(Weblog w) throws WebloggerException;
   378     
   379      
   380      /**
   381       * Get count of active weblogs
   382       */    
   383      public long getWeblogCount() throws WebloggerException;
   384  
   385      
   386      /**
   387       * Get count of enabled users
   388       */    
   389      public long getUserCount() throws WebloggerException; 
   390      
   391      
   392      /**
   393       * Release any resources held by manager.
   394       */
   395      public void release();
   396      
   397      
   398      /**
   399       * get a user by activation code
   400       * @param activationCode
   401       * @return
   402       * @throws WebloggerException
   403       */
   404      public User getUserByActivationCode(String activationCode) throws WebloggerException;
   405      
   406      /**
   407       * get a user by password request code
   408       * @param passwordRequestCode
   409       * @return
   410       * @throws WebloggerException
   411       */
   412      //public User getUserByPasswordRequestCode(String passwordRequestCode) throws WebloggerException;
   413  
   414  
   415  }