/**
* Copyright 1999-2009 The Pegadi Team
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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 CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.pegadi.server;
// RMI-imports
import no.dusken.common.model.Person;
import org.pegadi.games.Score;
import org.pegadi.model.*;
import org.pegadi.sources.Category;
import org.pegadi.sources.Contact;
import org.pegadi.sources.Source;
import org.pegadi.sqlsearch.SearchTerm;
import java.rmi.RemoteException;
import java.util.Date;
import java.util.List;
import java.util.Properties;
/**
* An RMI - interface
* <p/>
* All methods the various pegadi-clients can call, should be declared here
*
* @author Jørgen Binningsbø <jb@underdusken.no>
* @author Håvard Wigtil <havardw at pvv.org>
* @version $Id$
*/
public interface Server {
/**
* Saves a source to the db.
* If the source is new (has ID==-1), the source is inserted, if not
* it is updated.
*
* @throws NoAccessException
*/
public int saveSource(Source source, String sessionKey) throws NoAccessException;
/**
* Delete source from database
*/
public void deleteSource(Source source, String sessionKey) throws NoAccessException;
/**
* Searches a table for sources matching the search term
*/
public List<Source> getSourcesBySearchTerm(SearchTerm term, String sessionKey) throws NoAccessException;
/**
* Returns all categories in the DB
*/
public List<Category> getSourceCategories(String sessionKey) throws NoAccessException;
/**
* Add a category to database
*/
public void addSourceCategory(Category newCategory, String sessionKey) throws NoAccessException;
/**
* Update a category in the database (for renaming)
*/
public void updateSourceCategory(Category category, String sessionKey) throws NoAccessException;
/**
* Returns a source by it's ID
*/
public Source getSourceByID(int ID, String sessionKey) throws NoAccessException;
/**
* Returns all categories that the source with the ID is a mebmer of
*/
public List<Category> getCategoriesBySource(int sourceID, String sessionKey) throws NoAccessException;
/**
* updates the category memberships for the given source
*/
public void updateSourceCategoryMemberships(int sourceID, List<Category> members, String sessionKey) throws NoAccessException;
/**
* Delete a category in the database
*/
public void deleteSourceCategory(Category category, String sessionKey) throws NoAccessException;
/**
* Returns all contacts made with a given source
*/
public List<Contact> getContactsBySource(int sourceID, String sessionKey) throws NoAccessException;
/**
* Returns the URL of the root of the web application
*
* @throws NoAccessException
*/
public String getWebBase(String sessionKey) throws NoAccessException;
/**
* Returns the URL of the root of the web pages containing
* templates/stylesheets etc.
*
* @throws NoAccessException
*/
public String getWebXMLRoot(String sessionKey) throws NoAccessException;
/**
* Sends an email
*/
public boolean sendmail(String from, String to, String subject, String text, String sessionKey) throws NoAccessException;
public boolean sendmail(String from, List<String> to, String subject, String text, String sessionKey) throws NoAccessException;
// ================================
// User- and login-specific methods
// ================================
/**
* Authenticates the identitiy of the user.
* If this method is successful, the user shold now be able to access
* resticted methods.
*
* @param user Username
* @param pass Password
* @return A session key, or <code>null</code> on failure.
*/
public String login(String user, String pass);
/**
* Logs out this session. This will free all resources used by the session.
*
* @param sessionKey The session key.
* @throws NoAccessException If the session isn't valid.
*/
public void logout(String sessionKey) throws NoAccessException;
/**
* Returns the ID of the authtenticated user.
*
* @param sessionKey The session key.
* @return The user's ID.
* @throws NoAccessException If the session object is invalid.
*/
public String getUserID(String sessionKey) throws NoAccessException;
/**
* Returns the authenticated user. The authenticated user is the user owning
* the session.
*
* @return The authenticated user
* @throws NoAccessException If the session object is invalid.
*/
public Person getSessionUser(String sessionKey)
throws NoAccessException;
/**
* Finds a user by the user's ID.
*
* @param ID The ID to find.
* @return The user with the given ID.
*/
public Person getUser(String ID, String sessionKey) throws NoAccessException;
/**
* Finds a user by the user's ID.
*
* @param username The user's user name.
* @return The user with the given ID.
*/
public Person getUserByUsername(String username, String sessionKey) throws NoAccessException;
/**
* Persons used to be connected to an article by ID, not username.
* Fetch the person that used to have the given Id.
*/
public Person getUserByLegacyId(Integer legacyId, String sessionKey) throws NoAccessException;
/**
* Return an array of all users.
*
* @param sessionKey A valid session.
* @param inactive <code>true</code> if inactive users should be returned.
* @return An array of users.
*/
public List<Person> getUsers(boolean inactive, String sessionKey) throws NoAccessException;
/**
* Save an user preference. The domain-key combination need not exist,
* but if it exists it will be replaced.
*
* @param sessionKey A valid session.
* @param domain The preference domain.
* @param key The name of the preference.
* @param value The value of the preference.
*/
public void savePreference(String domain,
String key, String value, String sessionKey)
throws NoAccessException;
/**
* Get a single user preference. If there are no preference saved with
* the domain-key combination for the user this method will return
* <code>null</code>.
*
* @param domain The preference domain.
* @param key The name of the preference.
* @param session A valid session.
* @return The value of the preference, or <code>null</code>.
*/
public String getPreference(String domain, String key, String session)
throws NoAccessException;
/**
* Get all the preferences for a domain. The method will always return
* a valid <code>Properties</code> object, even if the domain does not
* exists for this user.
*
* @param domain The preference domain.
* @param session A valid session.
* @return All preferences for this domain. The object will be empty if no
* preferences were found.
*/
public Properties getPreferences(String domain, String session)
throws NoAccessException;
/**
* Tries to lock a given article.
*
* @throws NoAccessException
*/
public ArticleLock getArticleLock(int articleID, boolean transferIfSameUser, String sessionKey) throws NoAccessException;
/**
* Releases the lock on an article. This method must be called after closing an article.
*
* @param articleID The ID of the article to unlock.
* @throws NoAccessException
*/
public void releaseArticleLock(int articleID, String sessionKey) throws NoAccessException;
/**
* Returns an array of users who are allowed to edit a given article, excluding the owner of the article
*
* @param articleID The ID for the article to get a list of allowed users for.
* @return An array of <code>User</code>s who are allowed to edit the article
* @throws NoAccessException
*/
public List<Person> getCoJournalistsForArticle(int articleID, String sessionKey) throws NoAccessException;
/**
* Sets the users allowed to edit a given article, excluding the owner. Note that all the previous co-journalists
* who was set, is erased before the new ones are saved.
*
* @param articleID The article to grant access to.
* @param coJournalists The userIDs for the users allowed to edit the article
* @throws NoAccessException
*/
public void setCoJournalistsForArticle(int articleID, List<String> coJournalists, String sessionKey) throws NoAccessException;
/**
* Gets all the active Journalists.
*
* @return an array of <code>User</code>s
* @throws RemoteException if a RMI-error occurs
*/
public List<Person> getJournalists(String sessionKey) throws NoAccessException;
/**
* Gets all the active Photographers.
*
* @return an array of <code>User</code>s
* @throws RemoteException if an RMI-error occurs
*/
public List<Person> getPhotographers(String sessionKey) throws NoAccessException;
/**
* Gets the URI location of the Article
*
* @return a string with the URL
* @throws RemoteException if an RMI-error occurs
*/
public String getArticleLocation(String sessionKey) throws NoAccessException;
public boolean hasArticlePermission(String userId, int permissionId, int articleId, String sessionKey) throws NoAccessException;
public boolean hasGlobalPermission(String userId, int permissionId, String sessionKey) throws NoAccessException;
// ============================
// Publication-specific methods
// ============================
/**
* returns a publication to a client, when the client provides a
* correct ID-number.
*/
public Publication getPublicationByID(int ID, String sessionKey) throws NoAccessException;
/**
* returns all publications which are published a given year
*/
public List<Publication> getPublicationsByYear(int year, String sessionKey) throws NoAccessException;
/**
* returns all active publications. (active = not yet printed)
*
* @throws RemoteException
*/
public List<Publication> getActivePublications(String sessionKey) throws RemoteException;
/**
* saves/updates a publication to the database.
* id > 0: update
* else: insert new publication and return id
*/
public int saveOrUpdatePublication(Publication pub, String sessionKey) throws NoAccessException;
/**
* Returns all years which have publications.
*
* @return an array of <code>int</code>'s
*/
public List<Integer> getYearsWithPublications(String sessionKey) throws NoAccessException;
// ===============================
// disposal-specific methods
// ===============================
public Disp getDisposalByID(int ID, String sessionKey) throws NoAccessException;
public Disp getDisposalByPublicationID(int publicationID, String sessionKey) throws NoAccessException;
public Disp createNewDisposal(int publicationID, String sessionKey) throws NoAccessException;
// ===============================
// disposal-page-specific methods
// ===============================
public List<DispPage> getPagesByDispId(int dispId, String sessionKey) throws NoAccessException;
public DispPage createDispPage(DispPage dispPage, String sessionKey) throws NoAccessException;
public void saveDispPage(DispPage dispPage, String sessionKey) throws NoAccessException;
public void saveDispPages(List<DispPage> dispPages, String sessionKey) throws NoAccessException;
public void deleteDispPage(DispPage dispPage, String sessionKey) throws NoAccessException;
public List<DispSection> getDispSections(String sessionKey) throws NoAccessException;
public List<DispSection> getActiveDispSections(String sessionKey) throws NoAccessException;
public DispSection getDispSectionById(int sectionId, String sessionKey) throws NoAccessException;
public void createDispSection(DispSection dispSection, String sessionKey) throws NoAccessException;
public void saveDispSection(DispSection dispSection, String sessionKey) throws NoAccessException;
public void addArticleToPage(DispPage page, Article article, String sessionKey) throws NoAccessException;
public void removeArticleFromPAge(DispPage page, Article article, String sessionKey) throws NoAccessException;
// ===============================
// article-specific methods
// ===============================
/**
* Returns the Article with the given ID.
*
* @param ID The article's ID.
* @param sessionKey
* @throws NoAccessException If the session key is invalid.
*/
public Article getArticleByID(int ID, String sessionKey)
throws NoAccessException;
public List<Article> getArticlesByPageID(int pageId, String sessionKey) throws NoAccessException;
public List<Article> getArticlesByDispID(int dispId, String sessionKey) throws NoAccessException;
/**
* Returns all articles matching the specified searchterm.
*
* @param searchTerm The searchterm
* @param sessionKey
* @return All articles matching the searchterm
* @throws RemoteException
* @throws NoAccessException
*/
public List<Article> getArticlesBySearchTerm(SearchTerm searchTerm, String sessionKey) throws NoAccessException;
/**
* Returns all available article types.
*
* @return an array of <code>ArticleType</code>s.
* @throws RemoteException if an RMI-error occurs.
*/
public List<ArticleType> getArticleTypes(String sessionKey) throws NoAccessException;
/**
* Returns all available article statuses.
*
* @return an array of <code>ArticleStatus</code>s.
* @throws RemoteException if an RMI-error occurs
*/
public List<ArticleStatus> getArticleStatuses(String sessionKey) throws NoAccessException;
/**
* Save an article. If the articleID is 0, a new article is inserted into the database
* and the new ID is returned.
*
* @param article The article to save.
* @param sessionKey
* @return New articleID if new article is created or 0 for successful save of existing article. Returnvalue less than 0
* means that something was wrong, and the article was not successfully saved.
* @throws NoAccessException If the user is not allowed to edit the article.
*/
public int saveArticle(Article article, String sessionKey) throws NoAccessException;
public boolean deleteArticle(int articleID, String sessionKey) throws NoAccessException;
/**
* Save the text of an open article.
*
* @param articleID The ID of the article.
* @param text The text of the article.
* @param charCount Character count.
* @param sessionKey
*/
public boolean saveArticleText(int articleID, String text, int charCount, String sessionKey)
throws NoAccessException;
/**
* Save the text of an open article.
*
* @param article The article.
* @param sessionKey
*/
public boolean saveArticleText(Article article, String sessionKey)
throws NoAccessException;
public Stylesheet getStylesheet(PublishingMediaEnum publishingMedia, Section section, String sessionKey) throws NoAccessException;
public List<Section> getDepartments(String sessionKey) throws NoAccessException;
/**
* Returns the template for the given article. This method will return
* <code>null</code> if the template isn't found.
*
* @param articleID The ID of the article.
* @return The template.
*/
public String getTemplate(int articleID, String sessionKey) throws NoAccessException;
// =========================================================================
// Game spesific methods
// =========================================================================
//
// Methods for recording scores
//
/**
* Starts score recording for a new game. The <code>Score</code> object that is
* returned <i>must</i> be used when calling {@link #updateScore } and
* {@link #endGame }, as each score has an unique ID.
*
* @param domain The domain for the game.
* @param sessionKey
* @return A new Score object, with the score set to 0. If the domain is not known,
* this method will return <code>null</code>.
*/
public Score startGame(String domain, String sessionKey) throws NoAccessException;
/**
* Updates the score for a running game. The <code>Score</code> object must have the
* same ID as the object returned by {@link #startGame}, and the client must set the
* new value for score before updating.
*
* @param score The current score.
* @param sessionKey
*/
public void updateScore(Score score, String sessionKey) throws NoAccessException;
/**
* Records the final score for a game.The <code>Score</code> object must have the
* same ID as the object returned by {@link #startGame}, and the client must set the
* final value for the score.
*
* @param score The final score.
* @param sessionKey
* @return The same score object, with the <code>active</code> property set to false.
* @see org.pegadi.games.Score#isActive
*/
public Score endGame(Score score, String sessionKey) throws NoAccessException;
/**
* Cancels a game in progress.
*
* @param score The game to cancel.
* @param sessionKey
*/
public void cancelGame(Score score, String sessionKey) throws NoAccessException;
//
// Method for getting score lists
//
/**
* Returns the <code>count</code> best scores ever.
*
* @param count Number of scores to return.
* @param domain The game domain
* @return List of scores.
* @see org.pegadi.games.Score
*/
public List<? extends Score> getHighScore(String domain, int count, boolean activesOnly, String sessionKey) throws NoAccessException;
/**
* Returns the <code>count</code> best scores for the given user ID.
*
* @param userID user ID to return scores for.
* @param count Number of scores to return.
* @param domain The game domain
* @return List of scores.
* @see org.pegadi.games.Score
*/
public List<? extends Score> getUserScoreByUserID(String domain, String userID, int count, String sessionKey) throws NoAccessException;
/**
* Returns the <code>count</code> best scores for the user with this session.
* This is a convenience method to get scores for the logged in user.
* If the session is invalid, this method will return <code>null</code>.
*
* @param count Number of scores to return.
* @param domain The game domain
* @return List of scores.
* @see org.pegadi.games.Score
*/
public List<? extends Score> getUserScore(String domain, int count, String sessionKey) throws NoAccessException;
/**
* Returns the <code>count</code> best scores the given date.
*
* @param day The date to return scores from.
* @param count Number of scores to return.
* @param domain The game domain
* @return List of scores.
* @see org.pegadi.games.Score
*/
public List<? extends Score> getDayScore(String domain, Date day, int count, String sessionKey) throws NoAccessException;
//
// Server testing methods
//
/**
* Sends an object to the server, and returns the same object. The object must implement
* <code>serializable</code>.
*
* @param obj An object
* @return The object returned
*/
public Object ping(Object obj);
/**
* Returns <code>true</code> if the server is alive. This method will always return
* true if it can contact the server, so instead of returning false an exception will
* be thrown.
*
* @return <code>true</code> if the server is alive.
* @see #ping(Object)
*/
public boolean ping();
}