[prev in list] [next in list] [prev in thread] [next in thread]
List: mina-commits
Subject: svn commit: r1856369 - /mina/site/trunk/content/mina-project/userguide/ch3-service/
From: elecharny () apache ! org
Date: 2019-03-27 5:51:45
Message-ID: 20190327055145.1FB8C3A0D67 () svn01-us-west ! apache ! org
[Download RAW message or body]
Author: elecharny
Date: Wed Mar 27 05:51:44 2019
New Revision: 1856369
URL: http://svn.apache.org/viewvc?rev=1856369&view=rev
Log:
Renamed chapter 3 pages
Added:
mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.1-io-service.mdtext
mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.2-io-service-details.mdtext
mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.3-acceptor.mdtext
mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.4-connector.mdtext
Removed:
mina/site/trunk/content/mina-project/userguide/ch3-service/acceptor.mdtext
mina/site/trunk/content/mina-project/userguide/ch3-service/connector.mdtext
mina/site/trunk/content/mina-project/userguide/ch3-service/io-service-details.mdtext
mina/site/trunk/content/mina-project/userguide/ch3-service/io-service.mdtext
Added: mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.1-io-service.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.1-io-service.mdtext?rev=1856369&view=auto
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.1-io-service.mdtext \
(added)
+++ mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.1-io-service.mdtext \
Wed Mar 27 05:51:44 2019 @@ -0,0 +1,159 @@
+Title: 3.1 - IO Service Introduction
+NavUp: ch3-service.html
+NavUpText: Chapter 3 - Service
+NavNext: ch3.2-io-service-details.html
+NavNextText: 3.2 - IoService Details
+Notice: 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.
+
+# 3.1 - IoService Introduction
+
+[IoService](http://mina.apache.org/mina-project/xref/org/apache/mina/core/service/IoService.html) \
provides basic **I/O** Service and manages **I/O** Sessions within **MINA**. Its one \
of the most crucial part of **MINA** Architecture. The implementing classes of \
_IoService_ and child interface, are where most of the low level **I/O** operations \
are handled. +
+# IoService Mind Map
+
+Let's try to see what are the responsibilities of the _IoService_ and it \
implementing class [AbstractIoService](http://mina.apache.org/mina-project/xref/org/apache/mina/core/service/AbstractIoService.html). \
Let's take a slightly different approach of first using a [Mind \
Map](http://en.wikipedia.org/wiki/Mind_map) and then jump into the inner working. The \
Mind Map was created using [XMind](http://www.xmind.net/). +
+
+
+## Responsabilities
+
+As seen in the previous graphic, The _IoService_ has many responsabilities :
+
+* sessions management : Creates and deletes sessions, detect idleness.
+* filter chain management : Handles the filtr chain, allowing the user to change the \
chain on the fly +* handler invocation : Calls the handler when some new message is \
received, etc +* statistics management : Updates the number of messages sent, bytes \
sent, and many others +* listeners management : Manages the Listeners a suer can set \
up +* communication management : Handles the transmission of data, in both side
+
+All those aspects will be described in the following chapters.
+
+## Interface Details
+
+_IoService_ is the base interface for all the _IoConnector_'s and _IoAcceptor_'s \
that provides **I/O** services and manages **I/O** sessions. The interface has all \
the functions need to perform **I/O** related operations. +
+Lets take a deep dive into the various methods in the interface
+
+* getTransportMetadata()
+* addListener()
+* removeListener()
+* isDisposing()
+* isDisposed()
+* dispose()
+* getHandler()
+* setHandler()
+* getManagedSessions()
+* getManagedSessionCount()
+* getSessionConfig()
+* getFilterChainBuilder()
+* setFilterChainBuilder()
+* getFilterChain()
+* isActive()
+* getActivationTime()
+* broadcast()
+* setSessionDataStructureFactory()
+* getScheduledWriteBytes()
+* getScheduledWriteMessages()
+* getStatistics()
+
+### getTransportMetadata()
+
+This method returns the Transport meta-data the _IoAcceptor_ or _IoConnector_ is \
running. The typical details include provider name (nio, apr, rxtx), connection type \
(connectionless/connection oriented) etc. +
+### addListener
+
+Allows to add a _IoServiceListener_ to listen to specific events related to \
_IoService_. +
+### removeListener
+
+Removes specified _IoServiceListener_ attached to this _IoService_.
+
+### isDisposing
+
+This method tells if the service is currently being disposed. As it can take a \
while, it's useful to know the current status of the service. +
+### isDisposed
+
+This method tells if the service has been disposed. A service will be considered as \
disposed only when all the resources it has allocated have been released. +
+### dispose
+
+This method releases all the resources the service has allocated. As it may take a \
while, the user should check the service status using the _isDisposing()_ and \
_isDisposed()_ to know if the service is now disposed completely. +
+Always call _dispose()_ when you shutdown a service !
+
+### getHandler
+
+Returns the _IoHandler_ associated with the service.
+
+### setHandler
+
+Sets the _IoHandler_ that will be responsible for handling all the events for the \
service. The handler contains your application logic ! +
+### getManagedSessions
+
+Returns the map of all sessions which are currently managed by this service. A \
managed session is a session which is added to the service listener. It will be used \
to process the idle sessions, and other session aspects, depending on the kind of \
listeners a user adds to a service. +
+### getManagedSessionCount
+
+Returns the number of all sessions which are currently managed by this service.
+
+### getSessionConfig
+
+Returns the session configuration.
+
+### getFilterChainBuilder
+
+Returns the _Filter_ chain builder. This is useful if one wants to add some new \
filter that will be injected when the sessions will be created. +
+### setFilterChainBuilder
+
+Defines the _Filter_ chain builder to use with the service.
+
+### getFilterChain
+
+Returns the current default _Filter_ chain for the service.
+
+### isActive
+
+Tells if the service is active or not.
+
+### getActivationTime
+
+Returns the time when this service was activated. It returns the last time when this \
service was activated if the service is not anymore active. +
+### broadcast
+
+Writes the given message to all the managed sessions.
+
+### setSessionDataStructureFactory
+
+Sets the _IoSessionDataStructureFactory_ that provides related data structures for a \
new session created by this service. +
+### getScheduledWriteBytes
+
+Returns the number of bytes scheduled to be written (ie, the bytes stored in memory \
waiting for the socket to be ready for write). +
+### getScheduledWriteMessages
+
+Returns the number of messages scheduled to be written (ie, the messages stored in \
memory waiting for the socket to be ready for write). +
+### getStatistics
+
+Returns the _IoServiceStatistics_ object for this service.
+
Added: mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.2-io-service-details.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.2-io-service-details.mdtext?rev=1856369&view=auto
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.2-io-service-details.mdtext \
(added)
+++ mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.2-io-service-details.mdtext \
Wed Mar 27 05:51:44 2019 @@ -0,0 +1,73 @@
+Title: 3.2 - IoService Details
+NavUp: ch3-service.html
+NavUpText: Chapter 3 - Service
+NavPrev: ch3.1-io-service.html
+NavPrevText: 3.1 - IoService Introduction
+NavNext: ch3.3-acceptor.html
+NavNextText: 3.3 - Acceptor
+Notice: 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.
+
+# 3.2 - IoService Details
+
+_IoService_ is an interface that is implemented by the two most important classes in \
**MINA** : +
+* IoAcceptor
+* IoConnector
+
+In order to build a server, you need to select an implementation of the _IoAcceptor_ \
interface. For client applications, you need to implement an implementation of the \
_IoConnector_ interface. +
+## IoAcceptor
+
+Basically, this interface is named because of the _accept()_ method, responsible for \
the creation of new connections between a client and the server. The server accepts \
incoming connection requests. +
+At some point, we could have named this interface 'Server' (and this is the new name \
in the coming **MINA 3.0**). +
+As we may deal with more than one kind of transport (TCP/UDP/...), we have more than \
one implementation for this interface. It would be very unlikely that you need to \
implement a new one. +
+We have many of those implementing classes
+
+* __NioSocketAcceptor__ : the non-blocking Socket transport _IoAcceptor_
+* __NioDatagramAcceptor__ : the non-blocking UDP transport _IoAcceptor_
+* __AprSocketAcceptor__ : the blocking Socket transport _IoAcceptor_, based on APR
+* __VmPipeSocketAcceptor__ : the in-VM _IoAcceptor_
+
+Just pick the one that fit your need.
+
+Here is the class diagram for the _IoAcceptor_ interfaces and classes :
+
+
+
+## IoConnector
+
+As we have to use an _IoAcceptor_ for servers, you have to implement the \
_IoConnector_ for clients. Again, we have many implementation classes : +
+* __NioSocketConnector__ : the non-blocking Socket transport _IoConnector_
+* __NioDatagramConnector__ : the non-blocking UDP transport _IoConnector_
+* __AprSocketConnector__ : the blocking Socket transport _IoConnector_, based on APR
+* __ProxyConnector__ : a _IoConnector_ providing proxy support
+* __SerialConnector__ : a _IoConnector_ for a serial transport
+* __VmPipeConnector__ : the in-VM _IoConnector_
+
+Just pick the one that fit your need.
+
+Here is the class diagram for the _IoConnector_ interfaces and classes :
+
+
+
+
+
Added: mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.3-acceptor.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.3-acceptor.mdtext?rev=1856369&view=auto
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.3-acceptor.mdtext \
(added)
+++ mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.3-acceptor.mdtext \
Wed Mar 27 05:51:44 2019 @@ -0,0 +1,122 @@
+Title: 3.3 - Acceptor
+NavUp: ch3-service.html
+NavUpText: Chapter 3 - Service
+NavPrev: ch3.2-io-service-details.html
+NavPrevText: 3.2 - IoService Details
+NavNext: ch3.4-connector.html
+NavNextText: 3.4 - Connector
+Notice: 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.
+
+# 3.3 - Acceptor
+
+In order to build a server, you need to select an implementation of the _IoAcceptor_ \
interface. +
+## IoAcceptor
+
+Basically, this interface is named because of the _accept()_ method, responsible for \
the creation of new connection between a client and the server. The server accepts \
incoming connection request. +
+At some point, we could have named this interface 'Server'.
+
+As we may deal with more than one kind of transport (TCP/UDP/...), we have more than \
one implementation for this interface. It would be very unlikely that you need to \
implement a new one. +
+We have many of those implementing classes
+
+* __NioSocketAcceptor__ : the non-blocking Socket transport _IoAcceptor_
+* __NioDatagramAcceptor__ : the non-blocking UDP transport _IoAcceptor_
+* __AprSocketAcceptor__ : the blocking Socket transport _IoAcceptor_, based on APR
+* __VmPipeSocketAcceptor__ : the in-VM _IoAcceptor_
+
+Just pick the one that fit your need.
+
+Here is the class diagram for the _IoAcceptor_ interfaces and classes :
+
+
+
+## Creation
+
+You first have to select the type of _IoAcceptor_ you want to instanciate. This is a \
choice you will made early in the process, as it all boils down to which network \
protocol you will use. Let's see with an example how it works : +
+ :::java
+ public TcpServer() throws IOException {
+ // Create a TCP acceptor
+ IoAcceptor acceptor = new NioSocketAcceptor();
+
+ // Associate the acceptor to an IoHandler instance (your application)
+ acceptor.setHandler(this);
+
+ // Bind : this will start the server...
+ acceptor.bind(new InetSocketAddress(PORT));
+
+ System.out.println("Server started...");
+ }
+
+That's it ! You have created a TCP server. If you want to start an UDP server, \
simply replace the first line of code : +
+ :::java
+ ...
+ // Create an UDP acceptor
+ IoAcceptor acceptor = new NioDatagramAcceptor();
+ ...
+
+## Disposal
+
+The service can be stopped by calling the _dispose()_ method. The service will be \
stopped only when all the pending sessions have been processed : +
+ :::java
+ // Stop the service, waiting for the pending sessions to be inactive
+ acceptor.dispose();
+
+You can also wait for every thread being executed to be properly completed by \
passing a boolean parameter to this method : +
+ :::java
+ // Stop the service, waiting for the processing session to be properly completed
+ acceptor.dispose( true );
+
+## Status
+
+You can get the _IoService_ status by calling one of the following methods :
+
+* _isActive()_ : true if the service can accept incoming requests
+* _isDisposing()_ : true if the _dispose()_ method has been called. It does not tell \
if the service is actually stopped (some sessions might be processed) +* \
_isDisposed()_ : true if the _dispose(boolean)_ method has been called, and the \
executing threads have been completed. +
+## Managing the IoHandler
+
+You can add or get the associated _IoHandler_ when the service has been \
instanciated. Youjust have to call the _setHandler(IoHandler)_ or _getHandler()_ \
methods. +
+## Managing the Filters chain
+
+if you want to manage the filters chain, you will have to call the \
_getFilterChain()_ method. Here is an example : +
+ :::java
+ // Add a logger filter
+ DefaultIoFilterChainBuilder chain = acceptor.getFilterChain();
+ chain.addLast("logger", new LoggingFilter());
+
+You can also create the chain before and set it into the service :
+
+ :::java
+ // Add a logger filter
+ DefaultIoFilterChainBuilder chain = new DefaultIoFilterChainBuilder();
+ chain.addLast("logger", new LoggingFilter());
+
+ // And inject the created chain builder in the service
+ acceptor.setFilterChainBuilder(chain);
+
+##
+
Added: mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.4-connector.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.4-connector.mdtext?rev=1856369&view=auto
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.4-connector.mdtext \
(added)
+++ mina/site/trunk/content/mina-project/userguide/ch3-service/ch3.4-connector.mdtext \
Wed Mar 27 05:51:44 2019 @@ -0,0 +1,45 @@
+Title: 3.4 - Connector
+NavUp: ch3-service.html
+NavUpText: Chapter 3 - Service
+NavPrev: ch3.3-acceptor.html
+NavPrevText: 3.3 - Acceptor
+NavNext: ../ch4-session/ch4-session.html
+NavNextText: Chapter 4 - Session
+Notice: 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.
+
+# 3.4 - Connector
+
+For client applications, you need to implement an implementation of the IoConnector \
interface. +
+## IoConnector
+
+As we have to use an IoAcceptor for servers, you have to implement the IoConnector. \
Again, we have many implementation classes : +
+* __NioSocketConnector__ : the non-blocking Socket transport Connector
+* __NioDatagramConnector__ : the non-blocking UDP transport * Connector*
+* __AprSocketConnector__ : the blocking Socket transport * Connector*, based on APR
+* __ProxyConnector__ : a Connector providing proxy support
+* __SerialConnector__ : a Connector for a serial transport
+* __VmPipeConnector__ : the in-VM * Connector*
+
+Just pick the one that fit your need.
+
+Here is the class diagram for the IoConnector interfaces and classes :
+
+
+
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic