jetstream-api 0.4.1__tar.gz → 0.4.2__tar.gz

{jetstream_api-0.4.1/jetstream_api.egg-info → jetstream_api-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.4.1
+Version: 0.4.2
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003

{jetstream_api-0.4.1 → jetstream_api-0.4.2}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
@@ -26,6 +26,7 @@ from .properties import (
     ILChannelSecurity,
     ILChannelBalanceMode,
     ILClusterNode,
+    ILClusterControlResult,
     ILClusterProperty,
     ILQmgrProperty,
     ILSessionProperty,
@@ -75,6 +76,7 @@ __all__ = [
     "ILChannelSecurity",
     "ILChannelBalanceMode",
     "ILClusterNode",
+    "ILClusterControlResult",
     "ILClusterProperty",
     "ILQmgrProperty",
     "ILSessionProperty",

{jetstream_api-0.4.1 → jetstream_api-0.4.2}/ilink/admin.py

@@ -22,6 +22,7 @@ from .properties import (
     ILChannelStatus,
     ILChannelType,
     ILChannelDirection,
+    ILClusterControlResult,
     ILClusterNode,
     ILClusterProperty,
     ILQmgrMinorProperty,
@@ -946,26 +947,165 @@ class ILAdminService:
         self.setClusterProperty(vo)
         return True
 
-    def startCluster(self, clusterName: str) -> None:
-        """ilcc 프로세스를 기동한다. 이미 떠 있으면 실패한다."""
+    def _clusterNodesArg(self, withNodes: bool) -> str:
+        """START/STOP CLUSTER 의 arg3 를 만든다.
+
+        Args:
+            withNodes (bool): 엮인 큐 관리자까지 제어할지.
+
+        Returns:
+            str: 기본이면 ``""``, 조정자만 다루면 ``"N"``.
+
+        Raises:
+            ILOperationException: ``withNodes=False`` 인데 엔진이 **rev 3315 미만**일 때.
+
+        Note:
+            구엔진은 이 인자를 **조용히 무시하고 큐 관리자까지 내린다.** 침묵하는
+            옵션은 "안 내린다"고 믿게 만들어 옵션이 없는 것보다 나쁘므로, 보내기 전에
+            막는다. 판정을 ``0 < revision`` 으로 한정한 이유는 버전 문자열을 파싱하지
+            못했을 때 정상 엔진에서 기능이 조용히 사라지지 않게 하기 위해서다.
+        """
+        if withNodes:
+            return ""
+        if 0 < self.revision < ILC.CLUSTER_NO_NODES_MIN_REVISION:
+            raise ILOperationException(
+                "MIMQE_NOT_SUPPORTED (withNodes=False requires engine rev "
+                f"{ILC.CLUSTER_NO_NODES_MIN_REVISION}+, current: {self.revision})"
+            )
+        return ILC.MIMQ_CLUSTER_NO_NODES
+
+    def startCluster(self, clusterName: str,
+                     withNodes: bool = True) -> "ILClusterControlResult":
+        """클러스터를 기동한다 - 기본은 **ilcc 와 엮인 큐 관리자를 함께** 올린다.
+
+        Args:
+            clusterName (str): 기동할 클러스터 이름.
+            withNodes (bool): 엮인 큐 관리자까지 함께 기동할지. 기본 True.
+                ``False`` 면 조정자(ilcc)만 올리고 데이터 평면은 건드리지 않는다.
+                **엔진 rev 3315 이상**에서만 쓸 수 있다.
+
+        Returns:
+            ILClusterControlResult: 제어된 노드 수와 **빠진 노드 목록**.
+                ``getSkipped()`` 이 0 이 아니면 일부 노드가 처리되지 않은 것이다.
+                엔진 rev 3317 미만은 집계를 싣지 않으므로 ``known`` 이 False 로 온다.
+
+        Raises:
+            ILOperationException: 이미 떠 있을 때(``MIMQE_CLUSTER_NOT_STOPPED``),
+                그런 클러스터가 없을 때, ``withNodes=False`` 인데 엔진이 rev 3315
+                미만일 때(``MIMQE_NOT_SUPPORTED``).
+            ILException: 통신 실패.
+
+        Warning:
+            **기본값은 조정자만 올리는 게 아니다.** 노드 목록에 있는 큐 관리자 중
+            **이 서비스 소관인 것**을 함께 기동한다(엔진 rev 3309+). 다른 서비스
+            소관 노드는 전파받은 그쪽 서비스가 올린다. "클러스터를 켠다 = 데이터
+            평면까지 켠다"는 뜻이라 그렇다.
+
+        .. warning:: 성공 반환이 "전부 떴다"는 뜻이 아니다
+
+            노드 제어는 **최선 노력**이라 일부가 빠져도 이 호출은 성공을 돌려준다.
+            빠진 노드는 반환값 :class:`ILClusterControlResult` 로 알려 주므로
+            **반드시 확인하라**(엔진 rev 3317+). 빠지는 경우는 이렇다.
+
+            - 개별 노드 제어가 실패했다(그 서비스가 로그를 남기고 다음 노드로 넘어간다).
+            - 다른 서비스 소관 노드인데 **전파가 닿지 못했다.** 그쪽 노드는 그대로 남는다.
+
+            큐 관리자 이름이 빈 노드도 제어 대상에서 빠지는데, 엔진 **rev 3319 부터
+            그런 노드는 애초에 저장이 거부**되므로 새로 만든 클러스터에서는 생기지
+            않는다. rev 3319 이전에 등록된 레거시 노드가 남아 있다면
+            :meth:`removeClusterNode` 후 :meth:`addClusterNode` 로 이름을 채워야 한다.
+
+            ::
+
+                r = svc.startCluster("CC1")
+                if r.getSkipped():
+                    print("제어 대상에서 빠진 노드:", r.getSkippedNodes())
+                print("제어한 노드 %d개" % r.getControlled())
+
+        Note:
+            요청만 보내고 돌아온다. 상태는 :meth:`getClusterProperty` 로 확인하라.
+
+        Example::
+
+            svc.startCluster("CC1")                     # 큐 관리자까지 함께
+            svc.startCluster("CC1", withNodes=False)    # 조정자(ilcc)만
+
+            for _ in range(30):
+                if svc.getClusterProperty("CC1").get_status_string() == "RUNNING":
+                    break
+                time.sleep(0.5)
+        """
         try:
             self._checkClusterSupported()
-            self.service.request(
+            res = self.service.request(
                 ILC.MIMQ_START_CLUSTER,
-                ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION,
                 clusterName,
+                "",
+                self._clusterNodesArg(withNodes),
             )
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION:
+                raise ILOperationException(
+                    res.getArg1() if res is not None else "no response")
+            return ILClusterControlResult(res.getArg1(), res.getArg2(), res.getArg3())
         except _PASSTHROUGH_EXCEPTIONS:
             raise
         except Exception as exc:
             raise ILException(exc) from exc
 
-    def stopCluster(self, clusterName: str) -> None:
-        """ilcc 프로세스를 정지한다.
+    def stopCluster(self, clusterName: str,
+                    withNodes: bool = True) -> "ILClusterControlResult":
+        """클러스터를 정지한다 - 기본은 **ilcc 와 엮인 큐 관리자를 함께** 내린다.
+
+        Args:
+            clusterName (str): 정지할 클러스터 이름.
+            withNodes (bool): 엮인 큐 관리자까지 함께 정지할지. 기본 True.
+                ``False`` 면 조정자(ilcc)만 내리고 **데이터 평면은 살려 둔다.**
+                **엔진 rev 3315 이상**에서만 쓸 수 있다.
+
+        Returns:
+            ILClusterControlResult: 제어된 노드 수와 **빠진 노드 목록**.
+                ``getSkipped()`` 이 0 이 아니면 일부 노드가 처리되지 않은 것이다.
+                엔진 rev 3317 미만은 집계를 싣지 않으므로 ``known`` 이 False 로 온다.
+
+        Raises:
+            ILOperationException: ``withNodes=False`` 인데 엔진이 rev 3315 미만일 때
+                (``MIMQE_NOT_SUPPORTED``).
+            ILException: 통신 실패.
 
         미기동 상태에서 호출해도 성공이다(큐관리자 STOP 관례와 같다).
         정지 후에는 서비스 자동 기동 대상에서도 빠진다 - startCluster 로 되살린다.
 
+        .. warning:: 기본값은 큐 관리자까지 내린다
+
+            노드 목록에 있는 큐 관리자 중 **이 서비스 소관인 것**을 함께 정지시킨다
+            (엔진 rev 3309+). 그 위에서 돌던 응용의 연결이 함께 끊어진다.
+            조정자만 내리고 데이터 평면을 살려 두려면 ``withNodes=False`` 를 쓴다.
+
+            **구엔진(rev 3315 미만)은 이 옵션을 조용히 무시하고 큐 관리자까지
+            내린다.** 그래서 이 라이브러리가 보내기 전에 막는다 - 안 내려갈 것이라
+            믿고 부르는 것이 가장 위험하기 때문이다.
+
+        .. warning:: 성공 반환이 "전부 내려갔다"는 뜻이 아니다
+
+            노드 제어는 **최선 노력**이라 일부가 빠져도 이 호출은 성공을 돌려준다.
+            빠진 노드는 반환값 :class:`ILClusterControlResult` 로 알려 주므로
+            **반드시 확인하라**(엔진 rev 3317+). 빠지는 경우는 이렇다.
+
+            - 개별 노드 제어가 실패했다(그 서비스가 로그를 남기고 다음 노드로 넘어간다).
+            - 다른 서비스 소관 노드인데 **전파가 닿지 못했다.** 그쪽 노드는 그대로 남는다.
+
+            큐 관리자 이름이 빈 노드도 제어 대상에서 빠지는데, 엔진 **rev 3319 부터
+            그런 노드는 애초에 저장이 거부**되므로 새로 만든 클러스터에서는 생기지
+            않는다. rev 3319 이전에 등록된 레거시 노드가 남아 있다면
+            :meth:`removeClusterNode` 후 :meth:`addClusterNode` 로 이름을 채워야 한다.
+
+            ::
+
+                r = svc.stopCluster("CC1")
+                if r.getSkipped():
+                    print("제어 대상에서 빠진 노드:", r.getSkippedNodes())
+                print("제어한 노드 %d개" % r.getControlled())
+
         .. warning:: 정지 완료를 기다리지 않는다
 
             요청만 보내고 바로 돌아온다. **곧바로** :meth:`removeCluster` 를 부르면
@@ -973,14 +1113,31 @@ class ILAdminService:
             :meth:`getClusterProperty` 의 상태가 ``STOPPED`` 가 될 때까지 확인하고
             진행하라 - 큐관리자와 달리 ``stopClusterWithStatus`` 같은 대기형 메서드가
             없다.
+
+        Example::
+
+            # 조정자만 내린다 - 큐 관리자는 계속 서비스한다 (ilcc 패치 등)
+            svc.stopCluster("CC1", withNodes=False)
+            svc.startCluster("CC1", withNodes=False)
+
+            # 클러스터를 통째로 내린다 (기본)
+            svc.stopCluster("CC1")
+            while svc.getClusterProperty("CC1").get_status_string() != "STOPPED":
+                time.sleep(0.5)
+            svc.removeCluster("CC1")
         """
         try:
             self._checkClusterSupported()
-            self.service.request(
+            res = self.service.request(
                 ILC.MIMQ_STOP_CLUSTER,
-                ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION,
                 clusterName,
+                "",
+                self._clusterNodesArg(withNodes),
             )
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION:
+                raise ILOperationException(
+                    res.getArg1() if res is not None else "no response")
+            return ILClusterControlResult(res.getArg1(), res.getArg2(), res.getArg3())
         except _PASSTHROUGH_EXCEPTIONS:
             raise
         except Exception as exc: