/*******************************************************************************
* Copyright (c) 2006, 2008 Steffen Pingel and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Xiaoyang Guan - initial API and implementation
*******************************************************************************/
package org.eclipse.mylyn.internal.trac.core.client;
import java.io.InputStream;
import java.util.Date;
import java.util.Map;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.mylyn.internal.trac.core.model.TracWikiPage;
import org.eclipse.mylyn.internal.trac.core.model.TracWikiPageInfo;
/**
* Interface for the WikiRPC API provided by the Trac XML-RPC Plugin
*
* @author Xiaoyang Guan
* @since 2.1
*/
public interface ITracWikiClient {
/**
* Render arbitrary wiki text as HTML
*
* @param sourceText
* wiki source text
* @param monitor
* TODO
* @return The HTML-formatted string of the wiki text
* @throws TracException
* thrown in case of a connection error
*/
public String wikiToHtml(String sourceText, IProgressMonitor monitor) throws TracException;
/**
* Validates the Trac XML-RPC WikiRPC API version of the repository
*
* @param monitor
* TODO
* @throws TracException
*/
public void validateWikiRpcApi(IProgressMonitor monitor) throws TracException;
/**
* Gets the list of the names of all pages from the repository
*
* @param monitor
* TODO
* @return The array of the names of all Wiki pages
* @throws TracException
*/
public String[] getAllWikiPageNames(IProgressMonitor monitor) throws TracException;
/**
* Gets the latest version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param monitor
* TODO
* @return the Wiki page at the latest version
* @throws TracException
*/
public TracWikiPage getWikiPage(String pageName, IProgressMonitor monitor) throws TracException;
/**
* Gets a specific version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param version
* the version of the Wiki page
* @param monitor
* TODO
* @return the Wiki page at the specified version
* @throws TracException
*/
public TracWikiPage getWikiPage(String pageName, int version, IProgressMonitor monitor) throws TracException;
/**
* Gets the information about the latest version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param monitor
* TODO
* @return The information about the page at the latest version
* @throws TracException
*/
public TracWikiPageInfo getWikiPageInfo(String pageName, IProgressMonitor monitor) throws TracException;
/**
* Gets the information about the specified version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param version
* the version of the Wiki page
* @param monitor
* TODO
* @return The information about the page at the specified version
* @throws TracException
*/
public TracWikiPageInfo getWikiPageInfo(String pageName, int version, IProgressMonitor monitor)
throws TracException;
/**
* Gets the information about all versions of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param monitor
* TODO
* @return array of TracWikiPageInfo that contains the information about all versions of the page
* @throws TracException
*/
public TracWikiPageInfo[] getWikiPageInfoAllVersions(String pageName, IProgressMonitor monitor)
throws TracException;
/**
* Gets the raw Wiki text of the latest version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param monitor
* TODO
* @return the raw Wiki text of the page, latest version
* @throws TracException
*/
public String getWikiPageContent(String pageName, IProgressMonitor monitor) throws TracException;
/**
* Gets the raw Wiki text of the specified version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param version
* the version of the Wiki page
* @param monitor
* TODO
* @return the raw Wiki text of the page, specified version
* @throws TracException
*/
public String getWikiPageContent(String pageName, int version, IProgressMonitor monitor) throws TracException;
/**
* Gets the rendered HTML of the latest version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param monitor
* TODO
* @return the rendered HTML of the page, latest version
* @throws TracException
*/
public String getWikiPageHtml(String pageName, IProgressMonitor monitor) throws TracException;
/**
* Gets the rendered HTML of the specified version of a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param version
* the version of the Wiki page
* @param monitor
* TODO
* @return the rendered HTML of the page, specified version
* @throws TracException
*/
public String getWikiPageHtml(String pageName, int version, IProgressMonitor monitor) throws TracException;
/**
* Gets the list of information about all pages that have been modified since a given date from the repository
*
* @param since
* the date from which the changes to the Wiki pages should be retrieved
* @param monitor
* TODO
* @return array of TracWikiPageInfo that contains the information about the modified pages
* @throws TracException
*/
public TracWikiPageInfo[] getRecentWikiChanges(Date since, IProgressMonitor monitor) throws TracException;
/**
* Writes the content of a Wiki page to the repository
*
* @param pageName
* the name of the Wiki page
* @param content
* the content of the page to be written
* @param attributes
* a Map used to set any Wiki-specific things, which the server can freely ignore or incorporate.
* Standard names are:
* <ul>
* <li>comment (String): A comment for the page.
* <li>minoredit (Boolean): This was a minor edit only.
* </ul>
* @param monitor
* TODO
* @return <code>true</code> if successful
* @throws TracException
*/
public boolean putWikipage(String pageName, String content, Map<String, Object> attributes, IProgressMonitor monitor)
throws TracException;
/**
* Gets the list of the names of attachments on a given Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param monitor
* TODO
* @return an array of the names of attachments on the given page. Returns an empty array if the page has no
* attachment or the page does not exist.
* @throws TracException
*/
public String[] listWikiPageAttachments(String pageName, IProgressMonitor monitor) throws TracException;
/**
* Gets the content of an attachment on a Wiki page from the repository
*
* @param pageName
* the name of the Wiki page
* @param fileName
* the name of the attachment file
* @param monitor
* TODO
* @return An InputStream of the content of the attachment
* @throws TracException
*/
public InputStream getWikiPageAttachmentData(String pageName, String fileName, IProgressMonitor monitor)
throws TracException;
/**
* Attach a file to a Wiki page on the repository.
* <p>
* Note: The standard implementation of WikiRPC API for uploading attachments may ignore the description of the
* attachment and always use <code>true</code> for <code>replace</code>
*
* @param pageName
* the name of the Wiki page
* @param fileName
* the name of the file to be attached
* @param description
* the description of the attachment
* @param in
* An InputStream of the content of the attachment
* @param replace
* whether to overwrite an existing attachment with the same filename
* @param monitor
* TODO
* @return The (possibly transformed) filename of the attachment. If <code>replace</code> is <code>true</code>, the
* returned name is always the same as the argument <code>fileName</code>; if <code>replace</code> is
* <code>false</code> and an attachment with name <code>fileName</code> already exists, a different name is
* generated for the new attachment by the repository server and the new name is returned.
* @throws TracException
*/
public String putWikiPageAttachmentData(String pageName, String fileName, String description, InputStream in,
boolean replace, IProgressMonitor monitor) throws TracException;
}