org.gitlab4j.api.WikisApi Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of gitlab4j-api Show documentation
Show all versions of gitlab4j-api Show documentation
GitLab4J-API (gitlab4j-api) provides a full featured Java client library for working with GitLab repositories and servers via the GitLab REST API.
/*
* The MIT License (MIT)
*
* Copyright (c) 2017 Greg Messner
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package org.gitlab4j.api;
import java.io.File;
import java.io.IOException;
import java.net.URL;
import java.util.List;
import java.util.Optional;
import java.util.stream.Stream;
import javax.ws.rs.core.GenericType;
import javax.ws.rs.core.Response;
import org.gitlab4j.api.models.WikiAttachment;
import org.gitlab4j.api.models.WikiPage;
/**
* This class implements the client side API for the GitLab Wikis API.
* See Wikis API at GitLab for more information.
*/
public class WikisApi extends AbstractApi {
public WikisApi(GitLabApi gitLabApi) {
super(gitLabApi);
}
/**
* Get a list of pages in project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @return a list of pages in the project's wiki
* @throws GitLabApiException if any exception occurs
*/
public List getPages(Object projectIdOrPath) throws GitLabApiException {
return (getPages(projectIdOrPath, false, getDefaultPerPage()).all());
}
/**
* Get a Pager of pages in project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param itemsPerPage the number of WikiPage instances that will be fetched per page
* @return a Pager of pages in project's wiki for the specified range
* @throws GitLabApiException if any exception occurs
*/
public Pager getPages(Object projectIdOrPath, int itemsPerPage) throws GitLabApiException {
return (getPages(projectIdOrPath, false, itemsPerPage));
}
/**
* Get a Stream of pages in project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @return a Pager of pages in project's wiki for the specified range
* @throws GitLabApiException if any exception occurs
*/
public Stream getPagesStream(Object projectIdOrPath) throws GitLabApiException {
return (getPages(projectIdOrPath, false, getDefaultPerPage()).stream());
}
/**
* Get a list of pages in project wiki for the specified page.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param page the page to get
* @param perPage the number of wiki-pages per page
* @return a list of pages in project's wiki for the specified range
* @throws GitLabApiException if any exception occurs
* @deprecated Will be removed in a future release, use {@link #getPages(Object, boolean, int)}
*/
public List getPages(Object projectIdOrPath, int page, int perPage) throws GitLabApiException {
Response response = get(Response.Status.OK, getPageQueryParams(page, perPage),
"projects", getProjectIdOrPath(projectIdOrPath), "wikis");
return response.readEntity(new GenericType>() {});
}
/**
* Get a List of pages in project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param withContent if true the results will include the pages content
* @return a List of pages in project's wiki for the specified range
* @throws GitLabApiException if any exception occurs
*/
public List getPages(Object projectIdOrPath, boolean withContent) throws GitLabApiException {
return (getPages(projectIdOrPath, withContent, getDefaultPerPage()).all());
}
/**
* Get a Pager of pages in project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param withContent if true the results will include the pages content
* @param itemsPerPage the number of WikiPage instances that will be fetched per page
* @return a Pager of pages in project's wiki for the specified range
* @throws GitLabApiException if any exception occurs
*/
public Pager getPages(Object projectIdOrPath, boolean withContent, int itemsPerPage) throws GitLabApiException {
GitLabApiForm formData = new GitLabApiForm().withParam("with_content", (withContent ? 1 : 0));
return (new Pager(this, WikiPage.class, itemsPerPage, formData.asMap(),
"projects", getProjectIdOrPath(projectIdOrPath), "wikis"));
}
/**
* Get a Stream of pages in project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param withContent if true the results will include the pages content
* @return a Stream of pages in project's wiki for the specified range
* @throws GitLabApiException if any exception occurs
*/
public Stream getPagesStream(Object projectIdOrPath, boolean withContent) throws GitLabApiException {
return (getPages(projectIdOrPath, withContent, getDefaultPerPage()).stream());
}
/**
* Get a single page of project wiki.
*
* GitLab Endpoint: GET /projects/:id/wikis/:slug
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param slug the slug of the project's wiki page
* @return the specified project Snippet
* @throws GitLabApiException if any exception occurs
*/
public WikiPage getPage(Object projectIdOrPath, String slug) throws GitLabApiException {
Response response = get(Response.Status.OK, null,
"projects", getProjectIdOrPath(projectIdOrPath), "wikis", slug);
return (response.readEntity(WikiPage.class));
}
/**
* Get a single page of project wiki as an Optional instance.
*
* GitLab Endpoint: GET /projects/:id/wikis/:slug
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param slug the slug of the project's wiki page
* @return the specified project Snippet as an Optional instance
*/
public Optional getOptionalPage(Object projectIdOrPath, String slug) {
try {
return (Optional.ofNullable(getPage(projectIdOrPath, slug)));
} catch (GitLabApiException glae) {
return (GitLabApi.createOptionalFromException(glae));
}
}
/**
* Creates a new project wiki page. The user must have permission to create new wiki page.
*
* GitLab Endpoint: POST /projects/:id/wikis
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param title the title of a snippet, required
* @param content the content of a wiki page, required
* @return a WikiPage instance with info on the created page
* @throws GitLabApiException if any exception occurs
*/
public WikiPage createPage(Object projectIdOrPath, String title, String content) throws GitLabApiException {
// one of title or content is required
GitLabApiForm formData = new GitLabApiForm()
.withParam("title", title)
.withParam("content", content);
Response response = post(Response.Status.CREATED, formData,
"projects", getProjectIdOrPath(projectIdOrPath), "wikis");
return (response.readEntity(WikiPage.class));
}
/**
* Updates an existing project wiki page. The user must have permission to change an existing wiki page.
*
* GitLab Endpoint: PUT /projects/:id/wikis/:slug
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param slug the slug of the project's wiki page, required
* @param title the title of a snippet, optional
* @param content the content of a page, optional. Either title or content must be supplied.
* @return a WikiPage instance with info on the updated page
* @throws GitLabApiException if any exception occurs
*/
public WikiPage updatePage(Object projectIdOrPath, String slug, String title, String content) throws GitLabApiException {
GitLabApiForm formData = new GitLabApiForm()
.withParam("title", title)
.withParam("slug", slug, true)
.withParam("content", content);
Response response = put(Response.Status.OK, formData.asMap(), "projects", getProjectIdOrPath(projectIdOrPath), "wikis", slug);
return (response.readEntity(WikiPage.class));
}
/**
* Deletes an existing project wiki page. This is an idempotent function and deleting a non-existent page does
* not cause an error.
*
* GitLab Endpoint: DELETE /projects/:id/wikis/:slug
*
* @param projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance
* @param slug the slug of the project's wiki page
* @throws GitLabApiException if any exception occurs
*/
public void deletePage(Object projectIdOrPath, String slug) throws GitLabApiException {
delete(Response.Status.NO_CONTENT, null, "projects", getProjectIdOrPath(projectIdOrPath), "wikis", slug);
}
/**
* Uploads a file to the attachment folder inside the wiki’s repository. The attachment folder is the uploads folder.
*
* POST /projects/:id/wikis/attachments
*
* @param projectIdOrPath projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance, required
* @param fileToUpload the File instance of the file to upload, required
* @return a FileUpload instance with information on the just uploaded file
* @throws GitLabApiException if any exception occurs
*/
public WikiAttachment uploadAttachment(Object projectIdOrPath, File fileToUpload) throws GitLabApiException {
return (uploadAttachment(projectIdOrPath, fileToUpload, null));
}
/**
* Uploads a file to the attachment folder inside the wiki’s repository. The attachment folder is the uploads folder.
*
* POST /projects/:id/wikis/attachments
*
* @param projectIdOrPath projectIdOrPath the project in the form of an Long(ID), String(path), or Project instance, required
* @param fileToUpload the File instance of the file to upload, required
* @param branch the name of the branch, defaults to the wiki repository default branch, optional
* @return a FileUpload instance with information on the just uploaded file
* @throws GitLabApiException if any exception occurs
*/
public WikiAttachment uploadAttachment(Object projectIdOrPath, File fileToUpload, String branch) throws GitLabApiException {
URL url;
try {
url = getApiClient().getApiUrl("projects", getProjectIdOrPath(projectIdOrPath), "wikis", "attachments");
} catch (IOException ioe) {
throw new GitLabApiException(ioe);
}
GitLabApiForm formData = new GitLabApiForm().withParam("branch", branch);
Response response = upload(Response.Status.CREATED, "file", fileToUpload, null, formData, url);
return (response.readEntity(WikiAttachment.class));
}
}