1. /*
  2. * @(#)RelationServiceMBean.java 1.26 04/02/10
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.management.relation;
  8. import javax.management.ObjectName;
  9. import javax.management.InstanceNotFoundException;
  10. import java.util.List;
  11. import java.util.Map;
  12. /**
  13. * The Relation Service is in charge of creating and deleting relation types
  14. * and relations, of handling the consistency and of providing query
  15. * mechanisms.
  16. *
  17. * @since 1.5
  18. */
  19. public interface RelationServiceMBean {
  20. /**
  21. * Checks if the Relation Service is active.
  22. * Current condition is that the Relation Service must be registered in the
  23. * MBean Server
  24. *
  25. * @exception RelationServiceNotRegisteredException if it is not
  26. * registered
  27. */
  28. public void isActive()
  29. throws RelationServiceNotRegisteredException;
  30. //
  31. // Accessors
  32. //
  33. /**
  34. * Returns the flag to indicate if when a notification is received for the
  35. * unregistration of an MBean referenced in a relation, if an immediate
  36. * "purge" of the relations (look for the relations no longer valid)
  37. * has to be performed, or if that will be performed only when the
  38. * purgeRelations method is explicitly called.
  39. * <P>true is immediate purge.
  40. *
  41. * @return true if purges are immediate.
  42. *
  43. * @see #setPurgeFlag
  44. */
  45. public boolean getPurgeFlag();
  46. /**
  47. * Sets the flag to indicate if when a notification is received for the
  48. * unregistration of an MBean referenced in a relation, if an immediate
  49. * "purge" of the relations (look for the relations no longer valid)
  50. * has to be performed, or if that will be performed only when the
  51. * purgeRelations method is explicitly called.
  52. * <P>true is immediate purge.
  53. *
  54. * @param thePurgeFlg flag
  55. *
  56. * @see #getPurgeFlag
  57. */
  58. public void setPurgeFlag(boolean thePurgeFlg);
  59. //
  60. // Relation type handling
  61. //
  62. /**
  63. * Creates a relation type (RelationTypeSupport object) with given
  64. * role infos (provided by the RoleInfo objects), and adds it in the
  65. * Relation Service.
  66. *
  67. * @param theRelTypeName name of the relation type
  68. * @param theRoleInfoArray array of role infos
  69. *
  70. * @exception IllegalArgumentException if null parameter
  71. * @exception InvalidRelationTypeException If:
  72. * <P>- there is already a relation type with that name
  73. * <P>- the same name has been used for two different role infos
  74. * <P>- no role info provided
  75. * <P>- one null role info provided
  76. */
  77. public void createRelationType(String theRelTypeName,
  78. RoleInfo[] theRoleInfoArray)
  79. throws IllegalArgumentException,
  80. InvalidRelationTypeException;
  81. /**
  82. * Adds given object as a relation type. The object is expected to
  83. * implement the RelationType interface.
  84. *
  85. * @param theRelTypeObj relation type object (implementing the
  86. * RelationType interface)
  87. *
  88. * @exception IllegalArgumentException if null parameter
  89. * @exception InvalidRelationTypeException if there is already a relation
  90. * type with that name
  91. */
  92. public void addRelationType(RelationType theRelTypeObj)
  93. throws IllegalArgumentException,
  94. InvalidRelationTypeException;
  95. /**
  96. * Retrieves names of all known relation types.
  97. *
  98. * @return ArrayList of relation type names (Strings)
  99. */
  100. public List getAllRelationTypeNames();
  101. /**
  102. * Retrieves list of role infos (RoleInfo objects) of a given relation
  103. * type.
  104. *
  105. * @param theRelTypeName name of relation type
  106. *
  107. * @return ArrayList of RoleInfo.
  108. *
  109. * @exception IllegalArgumentException if null parameter
  110. * @exception RelationTypeNotFoundException if there is no relation type
  111. * with that name.
  112. */
  113. public List getRoleInfos(String theRelTypeName)
  114. throws IllegalArgumentException,
  115. RelationTypeNotFoundException;
  116. /**
  117. * Retrieves role info for given role of a given relation type.
  118. *
  119. * @param theRelTypeName name of relation type
  120. * @param theRoleInfoName name of role
  121. *
  122. * @return RoleInfo object.
  123. *
  124. * @exception IllegalArgumentException if null parameter
  125. * @exception RelationTypeNotFoundException if the relation type is not
  126. * known in the Relation Service
  127. * @exception RoleInfoNotFoundException if the role is not part of the
  128. * relation type.
  129. */
  130. public RoleInfo getRoleInfo(String theRelTypeName,
  131. String theRoleInfoName)
  132. throws IllegalArgumentException,
  133. RelationTypeNotFoundException,
  134. RoleInfoNotFoundException;
  135. /**
  136. * Removes given relation type from Relation Service.
  137. * <P>The relation objects of that type will be removed from the
  138. * Relation Service.
  139. *
  140. * @param theRelTypeName name of the relation type to be removed
  141. *
  142. * @exception RelationServiceNotRegisteredException if the Relation
  143. * Service is not registered in the MBean Server
  144. * @exception IllegalArgumentException if null parameter
  145. * @exception RelationTypeNotFoundException If there is no relation type
  146. * with that name
  147. */
  148. public void removeRelationType(String theRelTypeName)
  149. throws RelationServiceNotRegisteredException,
  150. IllegalArgumentException,
  151. RelationTypeNotFoundException;
  152. //
  153. // Relation handling
  154. //
  155. /**
  156. * Creates a simple relation (represented by a RelationSupport object) of
  157. * given relation type, and adds it in the Relation Service.
  158. * <P>Roles are initialized according to the role list provided in
  159. * parameter. The ones not initialized in this way are set to an empty
  160. * ArrayList of ObjectNames.
  161. * <P>A RelationNotification, with type RELATION_BASIC_CREATION, is sent.
  162. *
  163. * @param theRelId relation identifier, to identify uniquely the relation
  164. * inside the Relation Service
  165. * @param theRelTypeName name of the relation type (has to be created
  166. * in the Relation Service)
  167. * @param theRoleList role list to initialize roles of the relation (can
  168. * be null).
  169. *
  170. * @exception RelationServiceNotRegisteredException if the Relation
  171. * Service is not registered in the MBean Server
  172. * @exception IllegalArgumentException if null parameter
  173. * @exception RoleNotFoundException if a value is provided for a role
  174. * that does not exist in the relation type
  175. * @exception InvalidRelationIdException if relation id already used
  176. * @exception RelationTypeNotFoundException if relation type not known in
  177. * Relation Service
  178. * @exception InvalidRoleValueException if:
  179. * <P>- the same role name is used for two different roles
  180. * <P>- the number of referenced MBeans in given value is less than
  181. * expected minimum degree
  182. * <P>- the number of referenced MBeans in provided value exceeds expected
  183. * maximum degree
  184. * <P>- one referenced MBean in the value is not an Object of the MBean
  185. * class expected for that role
  186. * <P>- an MBean provided for that role does not exist
  187. */
  188. public void createRelation(String theRelId,
  189. String theRelTypeName,
  190. RoleList theRoleList)
  191. throws RelationServiceNotRegisteredException,
  192. IllegalArgumentException,
  193. RoleNotFoundException,
  194. InvalidRelationIdException,
  195. RelationTypeNotFoundException,
  196. InvalidRoleValueException;
  197. /**
  198. * Adds an MBean created by the user (and registered by him in the MBean
  199. * Server) as a relation in the Relation Service.
  200. * <P>To be added as a relation, the MBean must conform to the
  201. * following:
  202. * <P>- implement the Relation interface
  203. * <P>- have for RelationService ObjectName the ObjectName of current
  204. * Relation Service
  205. * <P>- have a relation id that is unique and unused in current Relation Service
  206. * <P>- have for relation type a relation type created in the Relation
  207. * Service
  208. * <P>- have roles conforming to the role info provided in the relation
  209. * type.
  210. *
  211. * @param theRelObjectName ObjectName of the relation MBean to be added.
  212. *
  213. * @exception IllegalArgumentException if null parameter
  214. * @exception RelationServiceNotRegisteredException if the Relation
  215. * Service is not registered in the MBean Server
  216. * @exception NoSuchMethodException If the MBean does not implement the
  217. * Relation interface
  218. * @exception InvalidRelationIdException if:
  219. * <P>- no relation identifier in MBean
  220. * <P>- the relation identifier is already used in the Relation Service
  221. * @exception InstanceNotFoundException if the MBean for given ObjectName
  222. * has not been registered
  223. * @exception InvalidRelationServiceException if:
  224. * <P>- no Relation Service name in MBean
  225. * <P>- the Relation Service name in the MBean is not the one of the
  226. * current Relation Service
  227. * @exception RelationTypeNotFoundException if:
  228. * <P>- no relation type name in MBean
  229. * <P>- the relation type name in MBean does not correspond to a relation
  230. * type created in the Relation Service
  231. * @exception InvalidRoleValueException if:
  232. * <P>- the number of referenced MBeans in a role is less than
  233. * expected minimum degree
  234. * <P>- the number of referenced MBeans in a role exceeds expected
  235. * maximum degree
  236. * <P>- one referenced MBean in the value is not an Object of the MBean
  237. * class expected for that role
  238. * <P>- an MBean provided for a role does not exist
  239. * @exception RoleNotFoundException if a value is provided for a role
  240. * that does not exist in the relation type
  241. */
  242. public void addRelation(ObjectName theRelObjectName)
  243. throws IllegalArgumentException,
  244. RelationServiceNotRegisteredException,
  245. NoSuchMethodException,
  246. InvalidRelationIdException,
  247. InstanceNotFoundException,
  248. InvalidRelationServiceException,
  249. RelationTypeNotFoundException,
  250. RoleNotFoundException,
  251. InvalidRoleValueException;
  252. /**
  253. * If the relation is represented by an MBean (created by the user and
  254. * added as a relation in the Relation Service), returns the ObjectName of
  255. * the MBean.
  256. *
  257. * @param theRelId relation id identifying the relation
  258. *
  259. * @return ObjectName of the corresponding relation MBean, or null if
  260. * the relation is not an MBean.
  261. *
  262. * @exception IllegalArgumentException if null parameter
  263. * @exception RelationNotFoundException there is no relation associated
  264. * to that id
  265. */
  266. public ObjectName isRelationMBean(String theRelId)
  267. throws IllegalArgumentException,
  268. RelationNotFoundException;
  269. /**
  270. * Returns the relation id associated to the given ObjectName if the
  271. * MBean has been added as a relation in the Relation Service.
  272. *
  273. * @param theObjName ObjectName of supposed relation
  274. *
  275. * @return relation id (String) or null (if the ObjectName is not a
  276. * relation handled by the Relation Service)
  277. *
  278. * @exception IllegalArgumentException if null parameter
  279. */
  280. public String isRelation(ObjectName theObjName)
  281. throws IllegalArgumentException;
  282. /**
  283. * Checks if there is a relation identified in Relation Service with given
  284. * relation id.
  285. *
  286. * @param theRelId relation id identifying the relation
  287. *
  288. * @return boolean: true if there is a relation, false else
  289. *
  290. * @exception IllegalArgumentException if null parameter
  291. */
  292. public Boolean hasRelation(String theRelId)
  293. throws IllegalArgumentException;
  294. /**
  295. * Returns all the relation ids for all the relations handled by the
  296. * Relation Service.
  297. *
  298. * @return ArrayList of String
  299. */
  300. public List getAllRelationIds();
  301. /**
  302. * Checks if given Role can be read in a relation of the given type.
  303. *
  304. * @param theRoleName name of role to be checked
  305. * @param theRelTypeName name of the relation type
  306. *
  307. * @return an Integer wrapping an integer corresponding to possible
  308. * problems represented as constants in RoleUnresolved:
  309. * <P>- 0 if role can be read
  310. * <P>- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME
  311. * <P>- integer corresponding to RoleStatus.ROLE_NOT_READABLE
  312. *
  313. * @exception IllegalArgumentException if null parameter
  314. * @exception RelationTypeNotFoundException if the relation type is not
  315. * known in the Relation Service
  316. */
  317. public Integer checkRoleReading(String theRoleName,
  318. String theRelTypeName)
  319. throws IllegalArgumentException,
  320. RelationTypeNotFoundException;
  321. /**
  322. * Checks if given Role can be set in a relation of given type.
  323. *
  324. * @param theRole role to be checked
  325. * @param theRelTypeName name of relation type
  326. * @param theInitFlg flag to specify that the checking is done for the
  327. * initialization of a role, write access shall not be verified.
  328. *
  329. * @return an Integer wrapping an integer corresponding to possible
  330. * problems represented as constants in RoleUnresolved:
  331. * <P>- 0 if role can be set
  332. * <P>- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME
  333. * <P>- integer for RoleStatus.ROLE_NOT_WRITABLE
  334. * <P>- integer for RoleStatus.LESS_THAN_MIN_ROLE_DEGREE
  335. * <P>- integer for RoleStatus.MORE_THAN_MAX_ROLE_DEGREE
  336. * <P>- integer for RoleStatus.REF_MBEAN_OF_INCORRECT_CLASS
  337. * <P>- integer for RoleStatus.REF_MBEAN_NOT_REGISTERED
  338. *
  339. * @exception IllegalArgumentException if null parameter
  340. * @exception RelationTypeNotFoundException if unknown relation type
  341. */
  342. public Integer checkRoleWriting(Role theRole,
  343. String theRelTypeName,
  344. Boolean theInitFlg)
  345. throws IllegalArgumentException,
  346. RelationTypeNotFoundException;
  347. /**
  348. * Sends a notification (RelationNotification) for a relation creation.
  349. * The notification type is:
  350. * <P>- RelationNotification.RELATION_BASIC_CREATION if the relation is an
  351. * object internal to the Relation Service
  352. * <P>- RelationNotification.RELATION_MBEAN_CREATION if the relation is a
  353. * MBean added as a relation.
  354. * <P>The source object is the Relation Service itself.
  355. * <P>It is called in Relation Service createRelation() and
  356. * addRelation() methods.
  357. *
  358. * @param theRelId relation identifier of the updated relation
  359. *
  360. * @exception IllegalArgumentException if null parameter
  361. * @exception RelationNotFoundException if there is no relation for given
  362. * relation id
  363. */
  364. public void sendRelationCreationNotification(String theRelId)
  365. throws IllegalArgumentException,
  366. RelationNotFoundException;
  367. /**
  368. * Sends a notification (RelationNotification) for a role update in the
  369. * given relation. The notification type is:
  370. * <P>- RelationNotification.RELATION_BASIC_UPDATE if the relation is an
  371. * object internal to the Relation Service
  372. * <P>- RelationNotification.RELATION_MBEAN_UPDATE if the relation is a
  373. * MBean added as a relation.
  374. * <P>The source object is the Relation Service itself.
  375. * <P>It is called in relation MBean setRole() (for given role) and
  376. * setRoles() (for each role) methods (implementation provided in
  377. * RelationSupport class).
  378. * <P>It is also called in Relation Service setRole() (for given role) and
  379. * setRoles() (for each role) methods.
  380. *
  381. * @param theRelId relation identifier of the updated relation
  382. * @param theNewRole new role (name and new value)
  383. * @param theOldRoleValue old role value (List of ObjectName objects)
  384. *
  385. * @exception IllegalArgumentException if null parameter
  386. * @exception RelationNotFoundException if there is no relation for given
  387. * relation id
  388. */
  389. public void sendRoleUpdateNotification(String theRelId,
  390. Role theNewRole,
  391. List theOldRoleValue)
  392. throws IllegalArgumentException,
  393. RelationNotFoundException;
  394. /**
  395. * Sends a notification (RelationNotification) for a relation removal.
  396. * The notification type is:
  397. * <P>- RelationNotification.RELATION_BASIC_REMOVAL if the relation is an
  398. * object internal to the Relation Service
  399. * <P>- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is a
  400. * MBean added as a relation.
  401. * <P>The source object is the Relation Service itself.
  402. * <P>It is called in Relation Service removeRelation() method.
  403. *
  404. * @param theRelId relation identifier of the updated relation
  405. * @param theUnregMBeanList List of ObjectNames of MBeans expected
  406. * to be unregistered due to relation removal (can be null)
  407. *
  408. * @exception IllegalArgumentException if null parameter
  409. * @exception RelationNotFoundException if there is no relation for given
  410. * relation id
  411. */
  412. public void sendRelationRemovalNotification(String theRelId,
  413. List theUnregMBeanList)
  414. throws IllegalArgumentException,
  415. RelationNotFoundException;
  416. /**
  417. * Handles update of the Relation Service role map for the update of given
  418. * role in given relation.
  419. * <P>It is called in relation MBean setRole() (for given role) and
  420. * setRoles() (for each role) methods (implementation provided in
  421. * RelationSupport class).
  422. * <P>It is also called in Relation Service setRole() (for given role) and
  423. * setRoles() (for each role) methods.
  424. * <P>To allow the Relation Service to maintain the consistency (in case
  425. * of MBean unregistration) and to be able to perform queries, this method
  426. * must be called when a role is updated.
  427. *
  428. * @param theRelId relation identifier of the updated relation
  429. * @param theNewRole new role (name and new value)
  430. * @param theOldRoleValue old role value (List of ObjectName objects)
  431. *
  432. * @exception IllegalArgumentException if null parameter
  433. * @exception RelationServiceNotRegisteredException if the Relation
  434. * Service is not registered in the MBean Server
  435. * @exception RelationNotFoundException if no relation for given id.
  436. */
  437. public void updateRoleMap(String theRelId,
  438. Role theNewRole,
  439. List theOldRoleValue)
  440. throws IllegalArgumentException,
  441. RelationServiceNotRegisteredException,
  442. RelationNotFoundException;
  443. /**
  444. * Removes given relation from the Relation Service.
  445. * <P>A RelationNotification notification is sent, its type being:
  446. * <P>- RelationNotification.RELATION_BASIC_REMOVAL if the relation was
  447. * only internal to the Relation Service
  448. * <P>- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is
  449. * registered as an MBean.
  450. * <P>For MBeans referenced in such relation, nothing will be done,
  451. *
  452. * @param theRelId relation id of the relation to be removed
  453. *
  454. * @exception RelationServiceNotRegisteredException if the Relation
  455. * Service is not registered in the MBean Server
  456. * @exception IllegalArgumentException if null parameter
  457. * @exception RelationNotFoundException if no relation corresponding to
  458. * given relation id
  459. */
  460. public void removeRelation(String theRelId)
  461. throws RelationServiceNotRegisteredException,
  462. IllegalArgumentException,
  463. RelationNotFoundException;
  464. /**
  465. * Purges the relations.
  466. *
  467. * <P>Depending on the purgeFlag value, this method is either called
  468. * automatically when a notification is received for the unregistration of
  469. * an MBean referenced in a relation (if the flag is set to true), or not
  470. * (if the flag is set to false).
  471. * <P>In that case it is up to the user to call it to maintain the
  472. * consistency of the relations. To be kept in mind that if an MBean is
  473. * unregistered and the purge not done immediately, if the ObjectName is
  474. * reused and assigned to another MBean referenced in a relation, calling
  475. * manually this purgeRelations() method will cause trouble, as will
  476. * consider the ObjectName as corresponding to the unregistered MBean, not
  477. * seeing the new one.
  478. *
  479. * <P>The behavior depends on the cardinality of the role where the
  480. * unregistered MBean is referenced:
  481. * <P>- if removing one MBean reference in the role makes its number of
  482. * references less than the minimum degree, the relation has to be removed.
  483. * <P>- if the remaining number of references after removing the MBean
  484. * reference is still in the cardinality range, keep the relation and
  485. * update it calling its handleMBeanUnregistration() callback.
  486. *
  487. * @exception RelationServiceNotRegisteredException if the Relation
  488. * Service is not registered in the MBean Server.
  489. */
  490. public void purgeRelations()
  491. throws RelationServiceNotRegisteredException;
  492. /**
  493. * Retrieves the relations where a given MBean is referenced.
  494. * <P>This corresponds to the CIM "References" and "ReferenceNames"
  495. * operations.
  496. *
  497. * @param theMBeanName ObjectName of MBean
  498. * @param theRelTypeName can be null; if specified, only the relations
  499. * of that type will be considered in the search. Else all relation types
  500. * are considered.
  501. * @param theRoleName can be null; if specified, only the relations
  502. * where the MBean is referenced in that role will be returned. Else all
  503. * roles are considered.
  504. *
  505. * @return an HashMap, where the keys are the relation ids of the relations
  506. * where the MBean is referenced, and the value is, for each key,
  507. * an ArrayList of role names (as an MBean can be referenced in several
  508. * roles in the same relation).
  509. *
  510. * @exception IllegalArgumentException if null parameter
  511. */
  512. public Map findReferencingRelations(ObjectName theMBeanName,
  513. String theRelTypeName,
  514. String theRoleName)
  515. throws IllegalArgumentException;
  516. /**
  517. * Retrieves the MBeans associated to given one in a relation.
  518. * <P>This corresponds to CIM Associators and AssociatorNames operations.
  519. *
  520. * @param theMBeanName ObjectName of MBean
  521. * @param theRelTypeName can be null; if specified, only the relations
  522. * of that type will be considered in the search. Else all
  523. * relation types are considered.
  524. * @param theRoleName can be null; if specified, only the relations
  525. * where the MBean is referenced in that role will be considered. Else all
  526. * roles are considered.
  527. *
  528. * @return an HashMap, where the keys are the ObjectNames of the MBeans
  529. * associated to given MBean, and the value is, for each key, an ArrayList
  530. * of the relation ids of the relations where the key MBean is
  531. * associated to given one (as they can be associated in several different
  532. * relations).
  533. *
  534. * @exception IllegalArgumentException if null parameter
  535. */
  536. public Map findAssociatedMBeans(ObjectName theMBeanName,
  537. String theRelTypeName,
  538. String theRoleName)
  539. throws IllegalArgumentException;
  540. /**
  541. * Returns the relation ids for relations of the given type.
  542. *
  543. * @param theRelTypeName relation type name
  544. *
  545. * @return an ArrayList of relation ids.
  546. *
  547. * @exception IllegalArgumentException if null parameter
  548. * @exception RelationTypeNotFoundException if there is no relation type
  549. * with that name.
  550. */
  551. public List findRelationsOfType(String theRelTypeName)
  552. throws IllegalArgumentException,
  553. RelationTypeNotFoundException;
  554. /**
  555. * Retrieves role value for given role name in given relation.
  556. *
  557. * @param theRelId relation id
  558. * @param theRoleName name of role
  559. *
  560. * @return the ArrayList of ObjectName objects being the role value
  561. *
  562. * @exception RelationServiceNotRegisteredException if the Relation
  563. * Service is not registered
  564. * @exception IllegalArgumentException if null parameter
  565. * @exception RelationNotFoundException if no relation with given id
  566. * @exception RoleNotFoundException if:
  567. * <P>- there is no role with given name
  568. * <P>or
  569. * <P>- the role is not readable.
  570. *
  571. * @see #setRole
  572. */
  573. public List getRole(String theRelId,
  574. String theRoleName)
  575. throws RelationServiceNotRegisteredException,
  576. IllegalArgumentException,
  577. RelationNotFoundException,
  578. RoleNotFoundException;
  579. /**
  580. * Retrieves values of roles with given names in given relation.
  581. *
  582. * @param theRelId relation id
  583. * @param theRoleNameArray array of names of roles to be retrieved
  584. *
  585. * @return a RoleResult object, including a RoleList (for roles
  586. * successfully retrieved) and a RoleUnresolvedList (for roles not
  587. * retrieved).
  588. *
  589. * @exception RelationServiceNotRegisteredException if the Relation
  590. * Service is not registered in the MBean Server
  591. * @exception IllegalArgumentException if null parameter
  592. * @exception RelationNotFoundException if no relation with given id
  593. *
  594. * @see #setRoles
  595. */
  596. public RoleResult getRoles(String theRelId,
  597. String[] theRoleNameArray)
  598. throws RelationServiceNotRegisteredException,
  599. IllegalArgumentException,
  600. RelationNotFoundException;
  601. /**
  602. * Returns all roles present in the relation.
  603. *
  604. * @param theRelId relation id
  605. *
  606. * @return a RoleResult object, including a RoleList (for roles
  607. * successfully retrieved) and a RoleUnresolvedList (for roles not
  608. * readable).
  609. *
  610. * @exception IllegalArgumentException if null parameter
  611. * @exception RelationNotFoundException if no relation for given id
  612. * @exception RelationServiceNotRegisteredException if the Relation
  613. * Service is not registered in the MBean Server
  614. */
  615. public RoleResult getAllRoles(String theRelId)
  616. throws IllegalArgumentException,
  617. RelationNotFoundException,
  618. RelationServiceNotRegisteredException;
  619. /**
  620. * Retrieves the number of MBeans currently referenced in the
  621. * given role.
  622. *
  623. * @param theRelId relation id
  624. * @param theRoleName name of role
  625. *
  626. * @return the number of currently referenced MBeans in that role
  627. *
  628. * @exception IllegalArgumentException if null parameter
  629. * @exception RelationNotFoundException if no relation with given id
  630. * @exception RoleNotFoundException if there is no role with given name
  631. */
  632. public Integer getRoleCardinality(String theRelId,
  633. String theRoleName)
  634. throws IllegalArgumentException,
  635. RelationNotFoundException,
  636. RoleNotFoundException;
  637. /**
  638. * Sets the given role in given relation.
  639. * <P>Will check the role according to its corresponding role definition
  640. * provided in relation's relation type
  641. * <P>The Relation Service will keep track of the change to keep the
  642. * consistency of relations by handling referenced MBean unregistrations.
  643. *
  644. * @param theRelId relation id
  645. * @param theRole role to be set (name and new value)
  646. *
  647. * @exception RelationServiceNotRegisteredException if the Relation
  648. * Service is not registered in the MBean Server
  649. * @exception IllegalArgumentException if null parameter
  650. * @exception RelationNotFoundException if no relation with given id
  651. * @exception RoleNotFoundException if:
  652. * <P>- internal relation
  653. * <P>and
  654. * <P>- the role does not exist or is not writable
  655. * @exception InvalidRoleValueException if internal relation and value
  656. * provided for role is not valid:
  657. * <P>- the number of referenced MBeans in given value is less than
  658. * expected minimum degree
  659. * <P>or
  660. * <P>- the number of referenced MBeans in provided value exceeds expected
  661. * maximum degree
  662. * <P>or
  663. * <P>- one referenced MBean in the value is not an Object of the MBean
  664. * class expected for that role
  665. * <P>or
  666. * <P>- an MBean provided for that role does not exist
  667. * @exception RelationTypeNotFoundException if unknown relation type
  668. *
  669. * @see #getRole
  670. */
  671. public void setRole(String theRelId,
  672. Role theRole)
  673. throws RelationServiceNotRegisteredException,
  674. IllegalArgumentException,
  675. RelationNotFoundException,
  676. RoleNotFoundException,
  677. InvalidRoleValueException,
  678. RelationTypeNotFoundException;
  679. /**
  680. * Sets the given roles in given relation.
  681. * <P>Will check the role according to its corresponding role definition
  682. * provided in relation's relation type
  683. * <P>The Relation Service keeps track of the changes to keep the
  684. * consistency of relations by handling referenced MBean unregistrations.
  685. *
  686. * @param theRelId relation id
  687. * @param theRoleList list of roles to be set
  688. *
  689. * @return a RoleResult object, including a RoleList (for roles
  690. * successfully set) and a RoleUnresolvedList (for roles not
  691. * set).
  692. *
  693. * @exception RelationServiceNotRegisteredException if the Relation
  694. * Service is not registered in the MBean Server
  695. * @exception IllegalArgumentException if null parameter
  696. * @exception RelationNotFoundException if no relation with given id
  697. *
  698. * @see #getRoles
  699. */
  700. public RoleResult setRoles(String theRelId,
  701. RoleList theRoleList)
  702. throws RelationServiceNotRegisteredException,
  703. IllegalArgumentException,
  704. RelationNotFoundException;
  705. /**
  706. * Retrieves MBeans referenced in the various roles of the relation.
  707. *
  708. * @param theRelId relation id
  709. *
  710. * @return a HashMap mapping:
  711. * <P> ObjectName -> ArrayList of String (role
  712. * names)
  713. *
  714. * @exception IllegalArgumentException if null parameter
  715. * @exception RelationNotFoundException if no relation for given
  716. * relation id
  717. */
  718. public Map getReferencedMBeans(String theRelId)
  719. throws IllegalArgumentException,
  720. RelationNotFoundException;
  721. /**
  722. * Returns name of associated relation type for given relation.
  723. *
  724. * @param theRelId relation id
  725. *
  726. * @return the name of the associated relation type.
  727. *
  728. * @exception IllegalArgumentException if null parameter
  729. * @exception RelationNotFoundException if no relation for given
  730. * relation id
  731. */
  732. public String getRelationTypeName(String theRelId)
  733. throws IllegalArgumentException,
  734. RelationNotFoundException;
  735. }