You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by GitBox <gi...@apache.org> on 2018/12/06 17:55:31 UTC
[GitHub] asfgit closed pull request #93: IGNITE-10519 JavaDocs added
asfgit closed pull request #93: IGNITE-10519 JavaDocs added
URL: https://github.com/apache/ignite-teamcity-bot/pull/93
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/IJiraIntegration.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/IJiraIntegration.java
index f7f34e1f..d952b2fd 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/IJiraIntegration.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/IJiraIntegration.java
@@ -21,19 +21,23 @@
import org.apache.ignite.ci.user.ICredentialsProv;
/**
- *
+ * Reperesents methods to provide interaction with Jira servers.
*/
public interface IJiraIntegration {
/** Message to show user when JIRA ticket was successfully commented by the Bot. */
public static String JIRA_COMMENTED = "JIRA commented.";
/**
+ * Produce visa message(see {@link Visa}) based on passed
+ * parameters and publish it as a comment for specified ticket
+ * on Jira server.
+ *
* @param srvId TC Server ID to take information about token from.
* @param prov Credentials.
* @param buildTypeId Suite name.
* @param branchForTc Branch for TeamCity.
* @param ticket JIRA ticket full name. E.g. IGNITE-5555
- * @return {@code True} if JIRA was notified.
+ * @return {@link Visa} instance.
*/
public Visa notifyJira(String srvId, ICredentialsProv prov, String buildTypeId, String branchForTc,
String ticket);
@@ -44,9 +48,17 @@ public Visa notifyJira(String srvId, ICredentialsProv prov, String buildTypeId,
/** */
public void init(String srvId);
- /** */
+ /**
+ * @param ticketFullName Ticket full name (e.g IGNITE-8331)
+ *
+ * @return URL which is used as link to Jira ticket with specified name.
+ */
public String generateTicketUrl(String ticketFullName);
- /** */
+ /**
+ * @param ticketFullName Ticket full name (e.g IGNITE-8331)
+ *
+ * @return URL which is used as link to Jira comment with specified id.
+ */
public String generateCommentUrl(String ticketFullName, int commentId);
}
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/JiraIntegrationProvider.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/JiraIntegrationProvider.java
index b841df34..62a66185 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/JiraIntegrationProvider.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/JiraIntegrationProvider.java
@@ -27,7 +27,9 @@
import org.apache.ignite.ci.util.ExceptionUtil;
/**
- *
+ * Class for providing {@link IJiraIntegration} instance for specified Jira
+ * server. Instance for each server is cached with defining instance
+ * expiration time.
*/
public class JiraIntegrationProvider implements IJiraIntegrationProvider {
/** */
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/package-info.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/package-info.java
new file mode 100644
index 00000000..6b4e5b78
--- /dev/null
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/jira/package-info.java
@@ -0,0 +1,23 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+/**
+ * This package is inteneded for interracting with Jira servers. It contains
+ * classes which is needed for injection Jira integration service instance
+ * via Guice. And interfaces and classes which provide specified functionality.
+ */
+package org.apache.ignite.ci.jira;
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildObserver.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildObserver.java
index 98287d2e..4918c32d 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildObserver.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildObserver.java
@@ -29,7 +29,8 @@
import org.slf4j.LoggerFactory;
/**
- *
+ * {@link BuildObserver} provides opportunity for scheduled run of
+ * {@link ObserverTask} and controlling existing and new observations.
*/
public class BuildObserver {
/** Logger. */
@@ -67,7 +68,13 @@ public void stop() {
timer.cancel();
}
- /** */
+ /**
+ * {@link ObserverTask} will stop tracking status of observation for
+ * specified {@link ContributionKey}.
+ *
+ * @return {@code true} if observation which is connected with specified
+ * {@link ContributionKey} was stopped.
+ */
public boolean stopObservation(ContributionKey key) {
try {
return observerTask.removeBuildInfo(key);
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildsInfo.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildsInfo.java
index 6143f548..89dffc39 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildsInfo.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/BuildsInfo.java
@@ -30,9 +30,9 @@
import org.apache.ignite.ci.web.model.ContributionKey;
/**
- * Represents parameters to determine context of rerunned builds, list of build IDs
- * which were requested to rerun and provides methods to check status of
- * rerunned builds.
+ * Represents parameters to determine context of observed builds, list of build IDs
+ * which were requested for observing and provides methods to check status of
+ * observed builds.
*/
public class BuildsInfo {
/** Shows that all rerunned builds finished successfully. */
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/CompactBuildsInfo.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/CompactBuildsInfo.java
index df700481..90944200 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/CompactBuildsInfo.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/CompactBuildsInfo.java
@@ -25,7 +25,8 @@
import org.apache.ignite.ci.teamcity.ignited.IStringCompactor;
/**
- *
+ * Representation of {@link BuildsInfo} with compacted properties for more
+ * effective cache storing.
*/
public class CompactBuildsInfo {
/** */
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/ObserverTask.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/ObserverTask.java
index 41e19f0c..9210deab 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/ObserverTask.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/ObserverTask.java
@@ -44,6 +44,10 @@
/**
* Checks observed builds for finished status and comments JIRA ticket.
+ * All observations are mapped with {@link ContributionKey} which are produced
+ * from BuildsInfo and used as a key for specific observation. It interacts
+ * with {@link VisasHistoryStorage} as persistent storage. For more information
+ * see package-info.
*/
public class ObserverTask extends TimerTask {
/** Logger. */
@@ -69,7 +73,10 @@
ObserverTask() {
}
- /** */
+ /** Connect to {@link VisaHistoryStorage} to get observed
+ * {@link VisaRequest}. Chiefly it's used for reconstructing
+ * observations after server restart.
+ */
public void init() {
visasHistStorage.getLastVisas().stream()
.filter(req -> req.isObserving())
@@ -87,7 +94,11 @@ public void init() {
return infos.values();
}
- /** */
+ /**
+ * Add {@link BuildsInfo} for observation.
+ * Observation with similar to given {@link ContributionKey} will be
+ * overwritten.
+ */
public void addInfo(BuildsInfo info) {
visasHistStorage.updateLastVisaRequest(info.getContributionKey(), req -> req.setObservingStatus(false));
@@ -126,7 +137,7 @@ public boolean removeBuildInfo(ContributionKey key) {
}
/**
- *
+ * That method is runned by {@link ObserverTask} scheduled.
*/
@AutoProfiling
@MonitoredTask(name = "Build Observer")
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/package-info.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/package-info.java
new file mode 100644
index 00000000..a8644957
--- /dev/null
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/observer/package-info.java
@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+/**
+ * This package is intended for creating tasks which statuses and
+ * results will be observed scheduled. {@link BuildObserver},
+ * {@link BuildsInfo} and {@link ObserverTask} are used for automatic Jira
+ * Visa reporting for every {@link BuildsInfo} whose builds were finished.
+ * {@link BuildsInfo} is representation of observation request and contains
+ * context of observed builds. {@link BuildObserver} is used to run
+ * {@link ObserverTask} scheduled and register builds which status should be
+ * observed. {@link ObserverTask} uses
+ * {@link org.apache.ignite.ci.web.model.hist.VisasHistoryStorage} as
+ * persistent storage for observed {@link BuildsInfo} which are stored as
+ * property of {@link org.apache.ignite.ci.web.model.VisaRequest}. It's
+ * assumed that only one {@link BuildsInfo} observation should be for every
+ * {@link org.apache.ignite.ci.web.model.ContributionKey} in same time. And
+ * {@link org.apache.ignite.ci.web.model.VisaRequest} with which this
+ * observation is connected should be last in
+ * {@link org.apache.ignite.ci.web.model.hist.VisasHistoryStorage} request's
+ * list for specific {@link org.apache.ignite.ci.web.model.ContributionKey}.
+ * It's needed for proper changing of status and result of
+ * {@link org.apache.ignite.ci.web.model.VisaRequest} by {@link ObserverTask}.
+ * If happens an attempt to add observation
+ * for {@link org.apache.ignite.ci.web.model.ContributionKey} while current
+ * observation is not finished, then current observation will be marked as
+ * cancelled and overwritten by the new one.
+ *
+ */
+package org.apache.ignite.ci.observer;
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactContributionKey.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactContributionKey.java
index 217a9613..3cc8814f 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactContributionKey.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactContributionKey.java
@@ -21,7 +21,8 @@
import org.apache.ignite.ci.teamcity.ignited.IStringCompactor;
/**
- *
+ * Representation of {@link ContributionKey} with compacted properties for more
+ * effective cache storing.
*/
public class CompactContributionKey {
/** */
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisa.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisa.java
index b7392941..98dac46f 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisa.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisa.java
@@ -21,7 +21,8 @@
import org.jetbrains.annotations.Nullable;
/**
- *
+ * Representation of {@link Visa} with compacted properties for more
+ * effective cache storing.
*/
public class CompactVisa {
/** */
diff --git a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisaRequest.java b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisaRequest.java
index 5ce9a712..bf5b896b 100644
--- a/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisaRequest.java
+++ b/ignite-tc-helper-web/src/main/java/org/apache/ignite/ci/web/model/CompactVisaRequest.java
@@ -21,7 +21,8 @@
import org.apache.ignite.ci.teamcity.ignited.IStringCompactor;
/**
- *
+ * Representation of {@link CompactVisaRequest} with compacted properties for more
+ * effective cache storing.
*/
public class CompactVisaRequest {
/** */
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services