org.llorllale.youtrack.api.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of youtrack-api Show documentation
Fluent, object-oriented Java API for YouTrack.
The newest version!
/*
 * Copyright 2017 George Aristy
 *
 * 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.
 */

/**
 * Fluent, object-oriented API for YouTrack.
 * 
 * Login
 * YouTrack supports various authentication strategies. {@code youtrack-api} implements:
 * 
 *   Username/password
 *   Permanent tokens
 *   Anonymous sessions (ie. the guest user)
 *  
 * 
 * Example: 
 * {@code final Session session = new PermanentToken(youtrackUrl, myToken).login();}

 * See the {@link org.llorllale.youtrack.api.session} package for more info.
 * 
 * 
Main Entry Point
 * The main entrypoint for the API is the {@link org.llorllale.youtrack.api.YouTrack} interface. 
 * Obtain an instance of the default implementation like this:

 * {@code final YouTrack yt = new DefaultYouTrack(session);}.
 * 
 * Projects
 * The {@link org.llorllale.youtrack.api.Projects} interface is used to find 
 * {@link org.llorllale.youtrack.api.Project projects}.

 * Example: 
 *   {@code final Optional project = new DefaultYoutrack(session)
 *       .projects()          //returns the Projects interface
 *       .get("projectId");   //returns an Optional}
 * See interfaces {@link org.llorllale.youtrack.api.Projects} and 
 * {@link org.llorllale.youtrack.api.Project}.
 * 
 * Issues
 * You can find an {@link org.llorllale.youtrack.api.Issue issue} like this:

 *   {@code final Optional issue = project.issues().get("issueId");}
 * To create an issue, use 
 * {@link org.llorllale.youtrack.api.Issues#create(String, String)}:
 *   {@code final Issue is = project.issues().create("summary", "description");}
 * See {@link org.llorllale.youtrack.api.Issues} for more info.
 * 
 * Fields of an Issue
 * Note:

 * It is important to know that some fields typically found in most issue tracking software - like
 * State and Priority - are not first class citizens in
 * YouTrack, although they are typically present in project configurations on most teams. First 
 * class attributes of issues in YouTrack include properties such as {@code creationDate}, 
 * {@code summary}, and {@code description} (although optional). Behind the scenes, YouTrack 
 * supports fields like State and Priority through the use of 
 * custom fields that are configured (sometimes preconfigured) through a project's
 * settings.


 * Usage:

 * To access a project's preconfigured {@link org.llorllale.youtrack.api.Field fields}:
 *   {@code final Stream fields = project.fields().stream();}
 * To access all possible {@link org.llorllale.youtrack.api.FieldValue values} for a field:
 *   {@code final Stream values = projectField.values();}
 * Updating an issue's fields can be done via {@link org.llorllale.youtrack.api.Issue#update()}.
 * Example:
 *   {@code final ProjectField state = project.fields().stream()
 *        .filter(f -> "State".equals(f.name()))
 *        .findAny().get();
 *  final FieldValue done = state.values()
 *        .filter(v -> "Done".equals(v.asString())
 *        .findAny().get();
 *  final Issue issueUpdated = issue.update().field(state, done);}
 *
 * @since 0.9.0
 * @see Project Site.
 */
package org.llorllale.youtrack.api;