sergey-chugunov-1985 commented on a change in pull request #8325: URL: https://github.com/apache/ignite/pull/8325#discussion_r502399395
########## File path: modules/core/src/main/java/org/apache/ignite/maintenance/MaintenanceRegistry.java ########## @@ -0,0 +1,132 @@ +/* + * 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. + */ + +package org.apache.ignite.maintenance; + +import java.util.List; +import java.util.UUID; + +import org.apache.ignite.IgniteCheckedException; +import org.apache.ignite.lang.IgniteExperimental; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * {@link MaintenanceRegistry} is a service local to each Ignite node + * that allows to request performing maintenance actions on that particular node. + * + * <p> + * When a node gets into a situation when some specific actions are required + * it enters the special mode called maintenance mode. + * In maintenance mode it doesn't join to the rest of the cluster but still allows to connect to it + * with control.{sh|bat} script or via JXM interface and perform needed actions. + * </p> + * + * <p> + * Implementing new task for maintenance mode requires several pieces of code. + * + * <ul> + * <li> + * First, component requiring Maintenance Mode should be able to register new {@link MaintenanceTask} + * with {@link MaintenanceRegistry#registerMaintenanceTask(MaintenanceTask)} method. + * + * Registration could happen automatically (e.g. if component detects some emergency situation + * that requires user intervention) + * or by user request (e.g. for a planned maintenance that requires + * detaching node from the rest of the cluster). + * </li> + * <li> + * Component responsible for handling this {@link MaintenanceTask} + * on startup checks if the task is registered (thus it should go to Maintenance Mode). + * If task is found component provides to {@link MaintenanceRegistry} its own implementation + * of {@link MaintenanceWorkflowCallback} interface + * via method {@link MaintenanceRegistry#registerWorkflowCallback(UUID, MaintenanceWorkflowCallback)}. + * </li> + * <li> + * {@link MaintenanceWorkflowCallback} should provide {@link MaintenanceRegistry} with + * {@link MaintenanceAction}s that are able to resolve maintenance task, + * get information about it and so on. + * Logic of these actions is completely up to the component providing it + * and depends only on particular maintenance task. + * </li> + * <li> + * When maintenance task is fixed, it should be removed from {@link MaintenanceRegistry} + * with call {@link MaintenanceRegistry#unregisterMaintenanceTask(UUID)}. + * </li> + * </ul> + * </p> + */ +@IgniteExperimental +public interface MaintenanceRegistry { + /** + * @return {@code True} if any maintenance task was found. + */ + public boolean isMaintenanceMode(); + + /** + * @param task {@link MaintenanceTask} object with maintenance information that needs + * to be stored to maintenance registry. + * + * @throws IgniteCheckedException If handling or storing maintenance task failed. + * + * @return Previously registered {@link MaintenanceTask} with the same ID + * or null if no tasks were registered for this ID. + */ + public @Nullable MaintenanceTask registerMaintenanceTask(MaintenanceTask task) throws IgniteCheckedException; + + /** + * Deletes {@link MaintenanceTask} of given ID from maintenance registry. + * + * @param mntcId + */ + public void unregisterMaintenanceTask(UUID mntcId); Review comment: fixed ########## File path: modules/core/src/main/java/org/apache/ignite/maintenance/MaintenanceRegistry.java ########## @@ -0,0 +1,132 @@ +/* + * 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. + */ + +package org.apache.ignite.maintenance; + +import java.util.List; +import java.util.UUID; + +import org.apache.ignite.IgniteCheckedException; +import org.apache.ignite.lang.IgniteExperimental; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * {@link MaintenanceRegistry} is a service local to each Ignite node + * that allows to request performing maintenance actions on that particular node. + * + * <p> + * When a node gets into a situation when some specific actions are required + * it enters the special mode called maintenance mode. + * In maintenance mode it doesn't join to the rest of the cluster but still allows to connect to it + * with control.{sh|bat} script or via JXM interface and perform needed actions. + * </p> + * + * <p> + * Implementing new task for maintenance mode requires several pieces of code. + * + * <ul> + * <li> + * First, component requiring Maintenance Mode should be able to register new {@link MaintenanceTask} + * with {@link MaintenanceRegistry#registerMaintenanceTask(MaintenanceTask)} method. + * + * Registration could happen automatically (e.g. if component detects some emergency situation + * that requires user intervention) + * or by user request (e.g. for a planned maintenance that requires + * detaching node from the rest of the cluster). + * </li> + * <li> + * Component responsible for handling this {@link MaintenanceTask} + * on startup checks if the task is registered (thus it should go to Maintenance Mode). + * If task is found component provides to {@link MaintenanceRegistry} its own implementation + * of {@link MaintenanceWorkflowCallback} interface + * via method {@link MaintenanceRegistry#registerWorkflowCallback(UUID, MaintenanceWorkflowCallback)}. + * </li> + * <li> + * {@link MaintenanceWorkflowCallback} should provide {@link MaintenanceRegistry} with + * {@link MaintenanceAction}s that are able to resolve maintenance task, + * get information about it and so on. + * Logic of these actions is completely up to the component providing it + * and depends only on particular maintenance task. + * </li> + * <li> + * When maintenance task is fixed, it should be removed from {@link MaintenanceRegistry} + * with call {@link MaintenanceRegistry#unregisterMaintenanceTask(UUID)}. + * </li> + * </ul> + * </p> + */ +@IgniteExperimental +public interface MaintenanceRegistry { + /** + * @return {@code True} if any maintenance task was found. + */ + public boolean isMaintenanceMode(); + + /** + * @param task {@link MaintenanceTask} object with maintenance information that needs + * to be stored to maintenance registry. + * + * @throws IgniteCheckedException If handling or storing maintenance task failed. + * + * @return Previously registered {@link MaintenanceTask} with the same ID + * or null if no tasks were registered for this ID. + */ + public @Nullable MaintenanceTask registerMaintenanceTask(MaintenanceTask task) throws IgniteCheckedException; + + /** + * Deletes {@link MaintenanceTask} of given ID from maintenance registry. + * + * @param mntcId + */ + public void unregisterMaintenanceTask(UUID mntcId); + + /** + * Returns active {@link MaintenanceTask} by its ID. + * There are active tasks only when node entered Maintenance Mode. + * + * {@link MaintenanceTask} becomes active when node enters Maintenance Mode and doesn't resolve the task + * during maintenance prepare phase. + * + * @return {@link MaintenanceTask} object for given maintenance ID or null if no maintenance task was found. + */ + @Nullable public MaintenanceTask activeMaintenanceTask(UUID maitenanceId); + + /** + * @param id UUID of {@link MaintenanceTask} this callback is registered for. Review comment: fixed javadoc here and in other places in this class ########## File path: modules/core/src/main/java/org/apache/ignite/maintenance/MaintenanceTask.java ########## @@ -0,0 +1,82 @@ +/* + * 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. + */ + +package org.apache.ignite.maintenance; + +import java.util.UUID; + +import org.apache.ignite.lang.IgniteExperimental; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * Represents request to handle maintenance situation stored on disk. Review comment: I removed it from javadoc but we may want to cover this question in documentation. There is an intention to make file with Maintenance Tasks readable by user so he/she may read information from it and even delete it completely if maintenance situation is fixed by hands. ########## File path: modules/core/src/main/java/org/apache/ignite/maintenance/MaintenanceWorkflowCallback.java ########## @@ -0,0 +1,69 @@ +/* + * 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. + */ + +package org.apache.ignite.maintenance; + +import java.util.List; +import java.util.UUID; + +import org.apache.ignite.lang.IgniteExperimental; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * Abstraction to decouple interaction between {@link MaintenanceRegistry} + * and components that may require maintenance. + * + * If a component may cause node to enter maintenance mode, it should register this callback + * in {@link MaintenanceRegistry} using method {@link MaintenanceRegistry#registerWorkflowCallback(UUID, MaintenanceWorkflowCallback)} + * + * {@link MaintenanceRegistry} during its workflow will collect necessary information about maintenance for components + * without knowing implementation details of the components. + */ +@IgniteExperimental +public interface MaintenanceWorkflowCallback { + /** + * Called by {@link MaintenanceRegistry} and enables it to check if maintenance is still needed + * for component that provided this callback. + * + * User may fix maintenance situation by hand when node was down thus before going to maintenance mode + * we should be able to check if it is still necessary. + * + * @return {@code True} if maintenance is still needed for the component. + */ + public boolean proceedWithMaintenance(); Review comment: agree, renamed as you suggested ########## File path: modules/core/src/main/java/org/apache/ignite/maintenance/package-info.java ########## @@ -0,0 +1,22 @@ +/* + * 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. + */ + +/** + * <!-- Package description. --> Review comment: fixed ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
